Skip to main content

​
Search-level configuration (searchConfig)

Use searchConfig when one order or one search needs behavior that differs from your tenant defaults: different outbound channels, stricter attempt caps, a custom SLA, pre-known contacts, manual-review routing, or search-specific webhook handling.

​
Where to put it

Use caseField
Same behavior for every search in the orderdefaultSearchConfig
Different behavior for one searchsearchTypes[i].searchConfig
defaultSearchConfig is applied to each created search that does not have its own searchConfig.
Per-search searchConfig replaces defaultSearchConfig for that search. It does not merge section-by-section. If a search has searchConfig: { "channels": { "email": true } }, then only that channels override applies for that search; other sections fall back to tenant defaults, not to defaultSearchConfig.

​
Quick example

This order sets a 48-hour default SLA for searches that do not provide their own config, then makes the employment search email-only and gives it a high-priority HR contact. 
{
  "defaultSearchConfig": {
    "timing": {
      "searchSlaMinutes": 2880
    }
  },
  "searchTypes": [
    {
      "searchType": "EMPLOYMENT",
      "searchConfig": {
        "channels": {
          "email": true,
          "voice": false,
          "fax": false,
          "preferredChannel": "EMAIL"
        },
        "outbound": {
          "contactHints": [
            {
              "email": "hr@example.com",
              "priority": "HIGH"
            }
          ]
        }
      }
    },
    {
      "searchType": "EDUCATION"
    }
  ]
}
In this example:
  • The EDUCATION search inherits defaultSearchConfig.
  • The EMPLOYMENT search uses its own searchConfig and does not inherit the default SLA.
  • To keep the default SLA on the employment search too, include timing.searchSlaMinutes inside that search’s searchConfig.

​
Common Patterns

​
Prefer Email First

{
  "channels": {
    "email": true,
    "voice": true,
    "fax": false,
    "preferredChannel": "EMAIL"
  }
}
preferredChannel changes attempt order. It does not disable other enabled channels.

​
Use Only Provided Contacts

{
  "research": {
    "skipResearch": true
  },
  "outbound": {
    "contactHints": [
      {
        "email": "verifications@example.com",
        "priority": "HIGH"
      }
    ]
  }
}
When skipResearch=true, contactHints are required. Each hint must include at least one of email, phone, or fax.

​
Limit Outbound Attempts

{
  "outbound": {
    "maxAttemptsPerMethod": 3,
    "maxTotalAttempts": 6,
    "cancelOutboundOnTerminalInbound": true
  }
}
maxAttemptsPerMethod limits attempts per channel type. maxTotalAttempts is a hard cap across channels for a contact.

​
Route a Search to Manual Review

{
  "inbound": {
    "requireManualReview": true
  }
}
Verified inbound responses move the search to ACTION_REQUIRED for review instead of automatically completing it. 
{
  "notifications": {
    "webhookOverride": {
      "enabled": true,
      "closeoutEndpoints": {
        "EMPLOYMENT": "https://client.example.com/webhooks/employment-closeout"
      }
    }
  }
}
Use this when one search needs different webhook delivery from the rest of the order.

​
Validation Rules

Create-order requests are validated before an order is created. If defaultSearchConfig or searchTypes[i].searchConfig is invalid, the request is rejected. Key rules:
  • channels.preferredChannel must be EMAIL, VOICE, or FAX.
  • channels.blockedDestinations and channels.allowedDestinations are mutually exclusive.
  • channels.blockedDestinations and channels.allowedDestinations each allow up to 100 entries.
  • outbound.contactHints allows up to 50 entries.
  • Each contact hint must include at least one of email, phone, or fax.
  • research.skipResearch=true requires at least one valid contact hint.
  • timing.searchSlaMinutes and timing.outboundWindowMinutes must be at least 1.
  • timing.businessHours.timezone must be a valid IANA timezone, such as America/Chicago.
  • timing.businessHours.startTime must be earlier than endTime.
  • inbound.requireManualReview=true cannot be combined with inbound.autoCompleteOnVerification=false.
  • escalation.escalationWebhookUrl and webhook URL fields must be valid URLs.

​
Precedence

Runtime behavior is resolved in this order:
  1. System defaults
  2. Tenant policy
  3. defaultSearchConfig, if the search does not provide its own searchConfig
  4. searchTypes[i].searchConfig, if provided
Tenant and organization safety rules may still suppress a channel or destination even when searchConfig enables it.

​
Field Reference

For every supported field, type, range, and example, see SearchConfigDto. Related references: