> ## Documentation Index
> Fetch the complete documentation index at: https://documentation.theary.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# Search-level configuration (searchConfig)
> How to customize verification behavior per order or per search.
# Search-level configuration (`searchConfig`)
Use `searchConfig` when one order or one search needs behavior that differs from your organization 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 case | Field |
| ------------------------------------------- | ----------------------------- |
| Same behavior for every search in the order | `defaultSearchConfig` |
| Different behavior for one search | `searchTypes[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 organization defaults, not to `defaultSearchConfig`.
## Supported fields at a glance
| Level | Field | Type | Key rules |
| ---------------------- | ------------------------------------------ | ---------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `searchConfig` | `thirdPartyBan` | `string[]` | Canonical third-party vendor codes only. Values are trimmed, uppercased, deduplicated, capped at **50**, and must not include `UNKNOWN`. Ban wins over third-party deferral. |
| `searchConfig` | `channels` | `object` | Controls outbound channel enablement, preferred channel, and destination allow/block lists. |
| `channels` | `email`, `voice`, `fax` | `boolean` | Enables or disables each outbound channel for this search. |
| `channels` | `preferredChannel` | `EMAIL`, `VOICE`, or `FAX` | Changes first-attempt order; does not enable a disabled channel. |
| `channels` | `blockedDestinations` | `string[]` | Max **100**. Mutually exclusive with `allowedDestinations`. |
| `channels` | `allowedDestinations` | `string[]` | Max **100**. Mutually exclusive with `blockedDestinations`. |
| `searchConfig` | `timing` | `object` | Controls SLA, outbound retry spacing, and business-hours windows. |
| `timing` | `searchSlaMinutes` | `number` | Minimum `1`. |
| `timing` | `outboundWindowMinutes` | `number` | Minimum `1`. |
| `timing.businessHours` | `timezone` | `string` | Valid IANA timezone, such as `America/Chicago`. |
| `timing.businessHours` | `startTime`, `endTime` | `HH:mm` string | `startTime` must be earlier than `endTime`. |
| `timing.businessHours` | `allowedDays` | `number[]` | Values `0–6`, Sunday through Saturday. |
| `searchConfig` | `outbound` | `object` | Controls attempt caps, third-party deferral, and provided contacts. |
| `outbound` | `maxAttemptsPerMethod` | `number` | Range `1–20`. |
| `outbound` | `maxTotalAttempts` | `number` | Range `1–50`. |
| `outbound` | `cancelOutboundOnTerminalInbound` | `boolean` | Cancels remaining outbound after terminal inbound unless a stronger workflow rule applies. |
| `outbound` | `thirdPartyDeferral` | `boolean` | Defers third-party routing, unless the detected vendor is banned by `thirdPartyBan`. |
| `outbound` | `thirdPartyDeferralHours` | `number` | Range `1–720`. |
| `outbound` | `contactHints` | `ContactHint[]` | Max **50**. Required when `research.skipResearch=true`. |
| `contactHints[]` | `email`, `phone`, `fax` | `string` | Each hint must include at least one of these fields **or** a `thirdPartyVendor`. |
| `contactHints[]` | `thirdPartyVendor` | canonical vendor code or `UNKNOWN` | Seeds a known third-party verification vendor. The contact routes via the third-party path (`usesThirdParty=true`). Cannot also appear in `thirdPartyBan`. |
| `contactHints[]` | `thirdPartyCode` | `string` | Optional employer/account code at the vendor. Requires `thirdPartyVendor`. |
| `contactHints[]` | `name`, `title`, `department` | `string` | Optional display and routing metadata. |
| `contactHints[]` | `priority` | `HIGH`, `NORMAL`, or `LOW` | Omitted defaults to `NORMAL`. |
| `searchConfig` | `research.skipResearch` | `boolean` | When `true`, bypasses research and uses only `outbound.contactHints`. |
| `searchConfig` | `inbound.autoCompleteOnVerification` | `boolean` | `false` holds terminal verified inbound responses for QA. |
| `searchConfig` | `inbound.requireManualReview` | `boolean` | Routes inbound responses to human review. Cannot be combined with `autoCompleteOnVerification=false`. |
| `searchConfig` | `escalation.disableAutoEscalation` | `boolean` | Prevents automatic escalation paths for this search. |
| `searchConfig` | `escalation.escalationWebhookUrl` | `string` | Per-search escalation webhook URL override. |
| `searchConfig` | `escalation.disableThirdPartyEvent` | `boolean` | Suppresses all third-party events for this search; use `thirdPartyBan` for vendor-specific suppression. |
| `searchConfig` | `notifications.suppressNotifications` | `boolean` | Suppresses intermediate notifications only; terminal events still fire. |
| `searchConfig` | `notifications.includeRawInboundInWebhook` | `boolean` | Controls raw inbound content in inbound notification payloads. |
| `searchConfig` | `notifications.webhookOverride` | `Webhook config` | Full per-search webhook routing override. If both are set, `notifications.webhookOverride` takes priority; `escalation.escalationWebhookUrl` only applies as a fallback endpoint when `webhookOverride` is not set. |
| `searchConfig` | `qaDestinations` | `object` | **Non-production only.** Redirects this search's outbound attempts to test inboxes/numbers instead of the organization-level QA destination. Silently ignored (with a server-side warning logged) in production — real, researched contact destinations are always used there. |
| `qaDestinations` | `email` | `string` | Overrides the QA email destination for this search. |
| `qaDestinations` | `phone` | `string` | Overrides the QA phone destination for this search. |
| `qaDestinations` | `fax` | `string` | Overrides the QA fax destination for this search. |
For the detailed schema, including nested webhook target fields, see [Search config](/api-reference/schemas/search-config).
## 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.
```json theme={null}
{
"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
```json theme={null}
{
"channels": {
"email": true,
"voice": true,
"fax": false,
"preferredChannel": "EMAIL"
}
}
```
`preferredChannel` changes attempt order. It does not disable other enabled channels.
### Use Only Provided Contacts
```json theme={null}
{
"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`, or a `thirdPartyVendor`.
### Seed a Known Third-Party Vendor
When you already know the employer or institution verifies through a third-party service, seed it directly as a contact hint instead of relying on research to discover it.
```json theme={null}
{
"research": {
"skipResearch": true
},
"outbound": {
"contactHints": [
{
"name": "Acme Corp HR",
"thirdPartyVendor": "TALX_WORK_NUMBER",
"thirdPartyCode": "13739",
"email": "hr@acme.com",
"priority": "HIGH"
}
]
}
}
```
In this example:
* `thirdPartyVendor` must be a canonical vendor code (or `UNKNOWN` when the contact is known to be a third party but the vendor cannot be named). The seeded contact is flagged `usesThirdParty=true` and routed via the third-party path rather than the normal channel pipeline.
* `thirdPartyCode` is the optional employer/account code at the vendor. It maps to the contact method's `thirdPartyId`. It requires `thirdPartyVendor`. When omitted, the canonical vendor code is used as the routing identifier.
* The `email` is kept as a direct fallback. By default the third-party route takes precedence and cancels remaining direct outbound; set `escalation.disableThirdPartyEvent: true` to attempt the direct channels instead.
* Third-party hints are deduplicated against researched contacts (and one another) by canonical vendor code and `thirdPartyCode`. `UNKNOWN` vendors without a code are never deduplicated.
* A hint may declare `thirdPartyVendor` with no direct destination. Such a hint still counts as a reachable seed for `research.skipResearch=true`.
Do not seed a `thirdPartyVendor` that also appears in this search's `thirdPartyBan` — the request is rejected. The ban would suppress the very routing the hint sets up. Ban a different vendor, or remove the ban, or supply a direct `email`/`phone`/`fax` fallback on the hint.
### Limit Outbound Attempts
```json theme={null}
{
"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
```json theme={null}
{
"inbound": {
"requireManualReview": true
}
}
```
Verified inbound responses move the search to `ACTION_REQUIRED` for review instead of automatically completing it.
### Ban a Third-Party Vendor
```json theme={null}
{
"thirdPartyBan": ["TALX_WORK_NUMBER"]
}
```
Use canonical third-party vendor codes when a client does not want a search routed to a specific third-party provider. If research or inbound detects a banned vendor, the third-party webhook is suppressed and manual or outbound handling continues.
`thirdPartyBan` takes precedence over third-party deferral. A banned vendor does not receive a delayed third-party webhook.
See [Third-party ban](/guides/third-party-ban) for the client-facing guide, supported vendor-code list, and troubleshooting examples.
### Ban Multiple Third-Party Vendors
```json theme={null}
{
"thirdPartyBan": [
"TALX_WORK_NUMBER",
"NSCH"
]
}
```
Values are normalized before runtime policy resolution. For example, `" talx_work_number "`, `"TALX_WORK_NUMBER"`, and duplicate entries resolve to one canonical `TALX_WORK_NUMBER` value. Unknown codes and `UNKNOWN` are rejected.
### Ban Third Parties While Deferral Is Enabled
```json theme={null}
{
"thirdPartyBan": ["TALX_WORK_NUMBER"],
"outbound": {
"thirdPartyDeferral": true,
"thirdPartyDeferralHours": 72
}
}
```
If `TALX_WORK_NUMBER` is detected, the ban applies immediately. No pending third-party timer is created, and the deferred third-party webhook is not emitted later.
### Redirect Outbound to a QA Destination (Non-Production Only)
```json theme={null}
{
"qaDestinations": {
"email": "qa-inbox@example.com",
"phone": "+15555550100"
}
}
```
`qaDestinations` overrides the organization-level QA destination for this search only, so a single test search can be redirected without touching other searches on the organization. It has no effect in production — outbound always uses the real, researched contact destination there regardless of what is submitted. Omitted channels (here, `fax`) fall back to the organization-level QA destination, then the service default.
`qaDestinations` is a non-production testing aid, not an access control. It is enforced server-side at policy-resolution time — before outbound ever sees it — so it cannot leak a QA-only redirect into production even if a caller forgets to check the environment.
### Override Webhook Routing for One Search
```json theme={null}
{
"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`, or a `thirdPartyVendor`.
* `contactHints[].thirdPartyVendor` must be a canonical vendor code or `UNKNOWN`; unknown codes are rejected.
* `contactHints[].thirdPartyCode` requires `thirdPartyVendor` on the same hint.
* A `contactHints[].thirdPartyVendor` cannot also appear in `thirdPartyBan` for the same search.
* `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.
* `thirdPartyBan` must be an array of canonical third-party vendor codes with at most 50 entries. Values are trimmed, uppercased, and deduplicated; `UNKNOWN`, unknown codes, and non-array values are rejected.
* `qaDestinations` is accepted and validated in every environment, but is only applied in non-production. In production it is dropped during policy resolution (a warning is logged) and never reaches outbound.
## 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 [Search config](/api-reference/schemas/search-config).
Related references:
* [Create Order](/api-reference/endpoints/create-order)
* [Verification request](/api-reference/schemas/verification-request)
* [Search type](/api-reference/schemas/search-type)
* [Webhook config](/api-reference/schemas/webhook-config)