> ## 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 config
> Per-search and order-level policy overrides applied on top of organization policy.
# Search config
Search config captures per-search policy overrides. Omitted fields fall back to organization policy, then system defaults. All top-level sections are optional, with one conditional requirement: `research.skipResearch=true` requires at least one `outbound.contactHints[]` entry with `email`, `phone`, `fax`, or a `thirdPartyVendor`.
It can be supplied in two places on a create-order request:
* `searchTypes[i].searchConfig` — per-search overrides. When present (even as an empty `{}`), it **fully replaces** any request-level `defaultSearchConfig` for that search.
* `defaultSearchConfig` — order-level default applied to every created search whose per-search `searchConfig` is absent.
Merge semantics are **whole-object replace**, not section-wise merge. If you set `searchTypes[0].searchConfig = { channels: { email: true } }`, only the `channels` override is applied for that search; `timing`, `outbound`, etc. revert to organization/system defaults — they are **not** inherited from `defaultSearchConfig`.
## Fields
Most integrations only need one or two sections at a time. The tables below list every supported field by level so you can scan the shape first, then jump to examples.
### Top-level `searchConfig`
| Field | Required | Type | Description |
| ---------------- | -------- | ---------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `thirdPartyBan` | No | `string[]` | Canonical third-party vendor codes banned for this search. Accepted values are listed in the [Third-Party Vendor Reference](/webhooks/events#third-party-vendor-reference), excluding `UNKNOWN`. Values are trimmed, uppercased, deduplicated, and capped at **50** entries. Ban matching suppresses third-party routing/webhooks and lets manual/outbound handling continue. See [Third-party ban](/guides/third-party-ban). |
| `channels` | No | `object` | Outbound channel enablement, preferred channel, and destination allow/block lists. |
| `timing` | No | `object` | SLA, outbound follow-up window, and business-hours overrides. |
| `outbound` | No | `object` | Attempt caps, terminal-inbound auto-cancel, third-party deferral, and pre-known contact hints. |
| `research` | No | `object` | Automated research controls. |
| `inbound` | No | `object` | Verified inbound auto-complete and manual-review controls. |
| `escalation` | No | `object` | Automatic escalation controls and third-party event suppression. |
| `notifications` | No | `object` | Per-search notification suppression, raw inbound inclusion, and webhook routing overrides. |
| `qaDestinations` | No | `object` | **Non-production only.** Redirect this search's outbound to test email/phone/fax destinations. Accepted and validated in every environment, but applied only outside production. |
### `channels`
| Field | Required | Type | Description | | |
| --------------------- | -------- | ---------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `email` | No | `boolean` | Enable or disable email outbound for this search. Organization safety rules may still suppress email. | | |
| `voice` | No | `boolean` | Enable or disable voice outbound for this search. Organization safety rules may still suppress voice. | | |
| `fax` | No | `boolean` | Enable or disable fax outbound for this search. Organization safety rules may still suppress fax. | | |
| `preferredChannel` | No | \`EMAIL | VOICE | FAX\` | First-attempt channel preference. It orders enabled channels as preferred first, then remaining enabled channels. It does not enable a disabled channel. |
| `blockedDestinations` | No | `string[]` | Email addresses, phone numbers, or fax numbers to never attempt. Emails are lowercased; phone/fax values are reduced to digits with trailing 10-digit matching for US numbers. Max **100** entries. Mutually exclusive with `allowedDestinations`. | | |
| `allowedDestinations` | No | `string[]` | Destination allowlist; every other destination is suppressed. Uses the same normalization as `blockedDestinations`. Max **100** entries. Mutually exclusive with `blockedDestinations`. | | |
### `timing`
| Field | Required | Type | Description |
| ----------------------- | -------- | -------- | ----------------------------------------------------------------------------------------- |
| `searchSlaMinutes` | No | `number` | Maximum minutes before the search should be completed or escalated. Minimum `1`. |
| `outboundWindowMinutes` | No | `number` | Minimum minutes between outbound follow-up attempts to the same destination. Minimum `1`. |
| `businessHours` | No | `object` | Custom outbound window. See `timing.businessHours` below. |
### `timing.businessHours`
| Field | Required | Type | Description |
| ------------- | -------- | ---------- | ---------------------------------------------------------------------------------------------------------- |
| `timezone` | No | `string` | IANA timezone identifier, such as `America/Chicago`. Validated with `Intl.DateTimeFormat`. |
| `startTime` | No | `string` | Window start in `HH:mm` 24-hour format. Must be strictly earlier than `endTime`. |
| `endTime` | No | `string` | Window end in `HH:mm` 24-hour format. Must be strictly later than `startTime`. |
| `allowedDays` | No | `number[]` | Days of the week permitted for outbound. `0` = Sunday through `6` = Saturday. Each value must be in `0–6`. |
### `outbound`
| Field | Required | Type | Description |
| --------------------------------- | ----------- | --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `maxAttemptsPerMethod` | No | `number` | Maximum attempts per channel type, per contact. Range `1–20`. |
| `maxTotalAttempts` | No | `number` | Hard cap on total attempts across all channels per contact. Applied in addition to `maxAttemptsPerMethod`. Range `1–50`. |
| `cancelOutboundOnTerminalInbound` | No | `boolean` | Auto-cancel remaining outbound attempts when a terminal inbound response is received. A pending third-party task always cancels outbound regardless of this value. |
| `thirdPartyDeferral` | No | `boolean` | Defer third-party vendor outbound and try direct channels first. `thirdPartyBan` takes precedence when the detected vendor is banned. |
| `thirdPartyDeferralHours` | No | `number` | Hours to defer third-party outbound when `thirdPartyDeferral` is enabled. Range `1–720`. |
| `contactHints` | Conditional | `ContactHint[]` | Pre-known contacts used to seed outbound. Max **50** hints. **Required** when `research.skipResearch=true`. |
### `outbound.contactHints[]`
| Field | Required | Type | Description | | |
| ------------------ | ----------- | ---------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----- | --------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `name` | No | `string` | Optional display name. | | |
| `title` | No | `string` | Optional job title. | | |
| `department` | No | `string` | Optional department or team. | | |
| `email` | Conditional | `string` | Contact email. Each hint must include at least one of `email`, `phone`, or `fax`, or a `thirdPartyVendor`. | | |
| `phone` | Conditional | `string` | Contact phone number. Each hint must include at least one of `email`, `phone`, or `fax`, or a `thirdPartyVendor`. | | |
| `fax` | Conditional | `string` | Contact fax number. Each hint must include at least one of `email`, `phone`, or `fax`, or a `thirdPartyVendor`. | | |
| `thirdPartyVendor` | Conditional | canonical vendor code or `UNKNOWN` | Marks the hint as a known third-party verification vendor. The seeded contact is flagged `usesThirdParty=true` and routes via the third-party path. Cannot also appear in this search's `thirdPartyBan`. | | |
| `thirdPartyCode` | No | `string` | Optional employer/account code at the vendor; maps to the seeded method's `thirdPartyId`. Requires `thirdPartyVendor`. | | |
| `priority` | No | \`HIGH | NORMAL | LOW\` | Attempt ordering priority. Omitted value defaults to `NORMAL`. Hints use canonical confidence values: `HIGH` = `0.99`, `NORMAL` = `0.95`, `LOW` = `0.90`. |
When `research.skipResearch=true`, `contactHints` are the sole outbound seed and the research agent is not invoked. When `research.skipResearch=false`, hints are merged on top of researched contacts per history item and deduplicated by normalized destination. Third-party hints are deduplicated against researched contacts (and one another) by canonical vendor code and `thirdPartyCode`. By default a third-party contact takes precedence over direct outbound and cancels remaining attempts; use `escalation.disableThirdPartyEvent` to fall through to any direct destinations on the hint.
### `research`
| Field | Required | Type | Description |
| -------------- | -------- | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `skipResearch` | No | `boolean` | When `true`, bypasses the research agent and seeds the contact plan exclusively from `outbound.contactHints`. Requests with `skipResearch=true` must include at least one hint with `email`, `phone`, `fax`, or a `thirdPartyVendor`. |
### `inbound`
| Field | Required | Type | Description |
| ---------------------------- | -------- | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `autoCompleteOnVerification` | No | `boolean` | Automatically mark the search `COMPLETED` when a terminal verification response is received. When `false`, terminal verified inbounds are held for QA and emit `verification.action_required` with `HUMAN_ESCALATION`. |
| `requireManualReview` | No | `boolean` | Hold all inbound responses for human review before finalizing. Overrides `autoCompleteOnVerification`. Combining `requireManualReview=true` with `autoCompleteOnVerification=false` is rejected; omit `autoCompleteOnVerification` or set it to `true`. |
**Data-model implication when inbound is held for QA.**
When `requireManualReview=true` or `autoCompleteOnVerification=false` routes a verified inbound to QA, the persisted `VerificationResult.outcome` is set to `ACTION_REQUIRED` — **not** the extracted terminal outcome (`VERIFIED`, `NO_RECORD`, etc.). The extracted outcome is preserved in the activity/metadata trail for reviewers, but downstream consumers that read `VerificationResult.outcome` before QA resolution will see `ACTION_REQUIRED`. Once QA completes the manual review path, the outcome is updated to reflect the final decision.
If your integration assumes `VerificationResult.outcome` always mirrors the inbound response, either leave `autoCompleteOnVerification=true` or wait for the subsequent `verification.completed` event before reading the outcome.
### `escalation`
| Field | Required | Type | Description |
| ------------------------ | -------- | --------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `disableAutoEscalation` | No | `boolean` | Prevents automatic escalation paths such as no-actionable-contacts, no-actionable-outbound-methods, retry-cap-reached, and SLA-exceeded reassignment. Takes precedence over organization `humanEscalation.enabledForSource` policy. |
| `escalationWebhookUrl` | No | `string` | HTTPS URL that overrides escalation webhook delivery for this search. Installed as a fallback endpoint for outgoing `verification.action_required` events. Superseded by `notifications.webhookOverride` when both are set. |
| `disableThirdPartyEvent` | No | `boolean` | Suppresses the third-party `verification.action_required` webhook when a third-party vendor is detected. When `true`, outbound is not cancelled and workflow continues through enabled outbound channels. Applies broadly to all detected third parties, unlike `thirdPartyBan`, which is vendor-specific. |
### `notifications`
| Field | Required | Type | Description |
| ---------------------------- | -------- | ---------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `suppressNotifications` | No | `boolean` | Suppresses intermediate `verification.notification` events for this search. Terminal `verification.completed` and `verification.action_required` events still fire. |
| `includeRawInboundInWebhook` | No | `boolean` | Includes raw inbound content in outgoing inbound notification payloads. Explicitly set to `false` to strip raw body and attachment text from those notification events. |
| `webhookOverride` | No | `Webhook config` | Full per-search webhook override for notification and escalation delivery. Supersedes organization-level webhook routing and `escalation.escalationWebhookUrl`. See [Webhook config](/api-reference/schemas/webhook-config). |
### `notifications.webhookOverride` summary
| Field | Required | Type | Description | | |
| ------------------- | -------- | --------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
| `enabled` | No | `boolean` | Enable or disable the override for this search. | | |
| `secret` | No | `string` | Optional HMAC secret used to sign webhook deliveries. | | |
| `retryAttempts` | No | `number` | Number of retry attempts on delivery failure. Delivery clamps retries to at most 10; values outside `0–10` are accepted but clamped at delivery time. | | |
| `closeoutEndpoints` | No | `object` | Per-search-type closeout endpoints, such as `EMPLOYMENT` and `EDUCATION`. Each key maps to a URL string or one or more [Webhook target](/api-reference/schemas/webhook-target) entries. | | |
| `fallbackEndpoint` | No | \`string | object | array\` | Fallback endpoint used when no closeout endpoint matches the search type. Accepts a URL string, a `Webhook target` object, or an array of either. |
### `qaDestinations`
**Non-production only.** Values are accepted and validated in every environment, but applied only outside production. In production the real, researched contact destinations are always used and these values are ignored (a server-side warning is logged).
| Field | Required | Type | Description |
| ------- | -------- | -------- | -------------------------------------------------------------------------------------------------------------- |
| `email` | No | `string` | Redirects all outbound email for this search to this address instead of the organization-level QA inbox. |
| `phone` | No | `string` | Redirects all outbound voice calls for this search to this number instead of the organization-level QA number. |
| `fax` | No | `string` | Redirects all outbound faxes for this search to this number instead of the organization-level QA fax number. |
Precedence (non-production): search-level `qaDestinations` → organization policy QA destination → service default. Omitted channels fall back down that same chain.
## Examples
### Ban One Third-Party Vendor
```json theme={null}
{
"thirdPartyBan": ["TALX_WORK_NUMBER"]
}
```
### Ban Multiple Third-Party Vendors
```json theme={null}
{
"thirdPartyBan": [
"TALX_WORK_NUMBER",
"NSCH"
]
}
```
### Ban Vendors With Normalization
The API trims whitespace, uppercases values, and deduplicates before policy resolution. This request resolves to `["TALX_WORK_NUMBER", "NSCH"]`.
```json theme={null}
{
"thirdPartyBan": [
" talx_work_number ",
"TALX_WORK_NUMBER",
"nsch"
]
}
```
### Ban Third Parties While Deferral Is Enabled
`thirdPartyBan` wins over `outbound.thirdPartyDeferral`. If `TALX_WORK_NUMBER` is detected, no pending third-party timer is created and no delayed third-party webhook is emitted.
```json theme={null}
{
"thirdPartyBan": ["TALX_WORK_NUMBER"],
"outbound": {
"thirdPartyDeferral": true,
"thirdPartyDeferralHours": 72
}
}
```
### Email-Only Outbound With a Blocked Generic Inbox
```json theme={null}
{
"channels": {
"email": true,
"voice": false,
"fax": false,
"preferredChannel": "EMAIL",
"blockedDestinations": ["hr-noreply@company.com"]
}
}
```
### Weekday 9-5 Central With a 48-Hour SLA
```json theme={null}
{
"timing": {
"searchSlaMinutes": 2880,
"outboundWindowMinutes": 120,
"businessHours": {
"timezone": "America/Chicago",
"startTime": "09:00",
"endTime": "17:00",
"allowedDays": [1, 2, 3, 4, 5]
}
}
}
```
### Attempt Caps Plus Multiple Pre-Known Contacts
```json theme={null}
{
"outbound": {
"maxAttemptsPerMethod": 5,
"maxTotalAttempts": 12,
"cancelOutboundOnTerminalInbound": true,
"contactHints": [
{
"name": "Jane Doe",
"title": "HR Director",
"email": "jane.doe@company.com",
"phone": "+1 (555) 123-4567",
"priority": "HIGH"
},
{
"department": "Payroll",
"fax": "+1 (555) 555-0100",
"priority": "NORMAL"
}
]
}
}
```
### Skip Research and Use Only Provided Contacts
```json theme={null}
{
"research": { "skipResearch": true },
"outbound": {
"contactHints": [
{ "email": "verify@company.com", "priority": "HIGH" },
{ "phone": "+1 (555) 123-4567", "priority": "NORMAL" }
]
}
}
```
### Route Every Verified Inbound To QA
```json theme={null}
{
"inbound": { "requireManualReview": true }
}
```
### Email-Only Outbound Even When Any Third Party Is Detected
Use `escalation.disableThirdPartyEvent` when the search should suppress every third-party event, regardless of vendor. Use `thirdPartyBan` when suppression should apply only to specific vendor codes.
```json theme={null}
{
"channels": {
"email": true,
"voice": false,
"fax": false,
"preferredChannel": "EMAIL"
},
"escalation": {
"disableThirdPartyEvent": true
}
}
```
### Per-Search Webhook Override That Only Routes Completions
```json theme={null}
{
"notifications": {
"suppressNotifications": true,
"webhookOverride": {
"enabled": true,
"secret": "s3cret-per-search",
"retryAttempts": 3,
"closeoutEndpoints": {
"EMPLOYMENT": [
{
"url": "https://client.example.com/webhooks/employment-closeout",
"events": ["verification.completed"]
}
]
}
}
}
}
```
### Redirect Outbound to a QA Destination (Non-Production Only)
```json theme={null}
{
"qaDestinations": {
"email": "qa-inbox@example.com",
"phone": "+15555550100"
}
}
```
Omitted channels (here, `fax`) fall back to the organization-level QA destination, then the service default. This has no effect in production.
## Example
A search config combining most sections, as you might attach to a single search:
```json theme={null}
{
"thirdPartyBan": ["TALX_WORK_NUMBER", "NSCH"],
"channels": {
"email": true,
"voice": false,
"preferredChannel": "EMAIL",
"blockedDestinations": ["hr-noreply@company.com"]
},
"timing": {
"searchSlaMinutes": 2880,
"outboundWindowMinutes": 120,
"businessHours": {
"timezone": "America/Chicago",
"startTime": "09:00",
"endTime": "16:00",
"allowedDays": [1, 2, 3, 4, 5]
}
},
"outbound": {
"maxAttemptsPerMethod": 5,
"maxTotalAttempts": 12,
"cancelOutboundOnTerminalInbound": true,
"contactHints": [
{ "email": "hr@company.com", "priority": "HIGH" }
]
},
"research": { "skipResearch": false }
}
```
Attached to a create-order request either as a per-search override or an order-level default:
```json theme={null}
{
"defaultSearchConfig": {
"timing": { "outboundWindowMinutes": 120 }
},
"searchTypes": [
{
"searchType": "EMPLOYMENT",
"searchConfig": {
"thirdPartyBan": ["TALX_WORK_NUMBER"],
"channels": { "email": true, "preferredChannel": "EMAIL" },
"outbound": {
"contactHints": [{ "email": "hr@company.com", "priority": "HIGH" }]
}
}
},
{ "searchType": "EDUCATION" }
]
}
```
In this request:
* The `EMPLOYMENT` search gets its per-search overrides — `defaultSearchConfig` is **not** merged in (e.g. `outboundWindowMinutes` falls back to organization policy, **not** to `120`).
* The `EDUCATION` search has no per-search `searchConfig`, so it uses `defaultSearchConfig` (`outboundWindowMinutes: 120` on top of organization policy).
## Validation rules
* `channels.blockedDestinations` and `channels.allowedDestinations` are mutually exclusive; each is capped at **100** entries.
* Each `outbound.contactHints[]` entry must include **at least one** of `email`, `phone`, or `fax`, or a `thirdPartyVendor`; max **50** hints.
* `contactHints[].thirdPartyVendor` must be a canonical vendor code or `UNKNOWN`; unknown codes are rejected. `thirdPartyCode` requires `thirdPartyVendor`, and a hint's `thirdPartyVendor` cannot also appear in `thirdPartyBan`.
* `timing.businessHours.startTime` must be strictly earlier than `timing.businessHours.endTime`; `allowedDays` values must be in `0–6`.
* `timing.businessHours.timezone` must be a valid IANA timezone (validated via `Intl.DateTimeFormat`).
* `inbound.requireManualReview: true` combined with `inbound.autoCompleteOnVerification: false` is rejected at validation time — omit `autoCompleteOnVerification` or set it to `true`.
* `escalation.escalationWebhookUrl` and any URL fields inside `notifications.webhookOverride` are validated as URLs.
* `research.skipResearch: true` requires `outbound.contactHints` with at least one reachable contact (`email`, `phone`, `fax`, or a `thirdPartyVendor`) and bypasses the research agent at runtime. Channel-disabled contact methods are auto-suppressed; third-party hints route outside the channel pipeline and are never channel-suppressed.
* `thirdPartyBan` must be an array of canonical third-party vendor codes. `UNKNOWN`, malformed values, non-arrays, and unknown codes are rejected. Empty arrays are accepted and behave the same as omission.
* `qaDestinations` is accepted and validated in every environment, but only applied outside production; in production it is dropped during policy resolution (a warning is logged) and never reaches outbound.
* Unknown fields on `searchConfig` are not part of the public contract and may be ignored by runtime policy resolution; send only the fields documented above.
## Behavior precedence
Once a search is created, the runtime resolves its effective policy by layering organization defaults under the per-search overrides. These precedence rules apply at runtime:
* **Escalation gating:** `escalation.disableAutoEscalation=true` wins over organization-level `humanEscalation.enabledForSource`. When `disableAutoEscalation=false` (or omitted), the per-source organization flag is consulted.
* **Escalation webhook routing:** `notifications.webhookOverride` > `escalation.escalationWebhookUrl` > organization webhook config. Set one or the other, not both.
* **Inbound terminal routing:** `inbound.requireManualReview=true` routes verified inbounds to `ACTION_REQUIRED` regardless of `autoCompleteOnVerification`. When `requireManualReview=false`, `autoCompleteOnVerification=false` holds the search for QA as `ACTION_REQUIRED`; `autoCompleteOnVerification=true` (default) auto-completes.
* **Outbound cancel on terminal inbound:** a pending third-party task **always** cancels outbound, regardless of `outbound.cancelOutboundOnTerminalInbound`.
* **Third-party ban:** `thirdPartyBan` wins over immediate third-party routing, third-party deferral, and inbound third-party redirects for matching canonical vendors. Banned vendors may still appear in the contact plan for auditability, but third-party webhooks are not emitted.
* **Organization preferences:** applied **after** per-search channel overrides. An org-level channel block still suppresses a channel that `searchConfig.channels.*` enables — this is a safety rail.
* **Notification suppression:** `notifications.suppressNotifications` only affects intermediate `verification.notification` events. Terminal `verification.completed` and `verification.action_required` always fire.
* **Raw inbound stripping:** only applied when `notifications.includeRawInboundInWebhook` is **explicitly** `false`. Tenants that have not set the flag retain current behavior.
## Merge semantics
* When `searchTypes[i].searchConfig` is `undefined` or `null`, `defaultSearchConfig` applies for that search.
* When `searchTypes[i].searchConfig` is present — including `{}` — it **fully replaces** `defaultSearchConfig` for that search. Section-wise merging is not performed.
## Related schemas
* [Verification request](/api-reference/schemas/verification-request) — where `defaultSearchConfig` is attached.
* [Search type](/api-reference/schemas/search-type) — where per-search `searchConfig` is attached.
* [Webhook config](/api-reference/schemas/webhook-config) — shape of `notifications.webhookOverride`.