​

Search-level configuration (searchConfig)

Download this guide

​

Where to put it

​

Supported fields at a glance

​

Quick example

{
  "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"
    }
  ]
}

• 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"
  }
}

​

Use Only Provided Contacts

{
  "research": {
    "skipResearch": true
  },
  "outbound": {
    "contactHints": [
      {
        "email": "verifications@example.com",
        "priority": "HIGH"
      }
    ]
  }
}

​

Seed a Known Third-Party Vendor

{
  "research": {
    "skipResearch": true
  },
  "outbound": {
    "contactHints": [
      {
        "name": "Acme Corp HR",
        "thirdPartyVendor": "TALX_WORK_NUMBER",
        "thirdPartyCode": "13739",
        "email": "hr@acme.com",
        "priority": "HIGH"
      }
    ]
  }
}

• 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.

​

Limit Outbound Attempts

{
  "outbound": {
    "maxAttemptsPerMethod": 3,
    "maxTotalAttempts": 6,
    "cancelOutboundOnTerminalInbound": true
  }
}

​

Route a Search to Manual Review

{
  "inbound": {
    "requireManualReview": true
  }
}

​

Ban a Third-Party Vendor

{
  "thirdPartyBan": ["TALX_WORK_NUMBER"]
}

​

Ban Multiple Third-Party Vendors

{
  "thirdPartyBan": [
    "TALX_WORK_NUMBER",
    "NSCH"
  ]
}

​

Ban Third Parties While Deferral Is Enabled

{
  "thirdPartyBan": ["TALX_WORK_NUMBER"],
  "outbound": {
    "thirdPartyDeferral": true,
    "thirdPartyDeferralHours": 72
  }
}

​

Override Webhook Routing for One Search

{
  "notifications": {
    "webhookOverride": {
      "enabled": true,
      "closeoutEndpoints": {
        "EMPLOYMENT": "https://client.example.com/webhooks/employment-closeout"
      }
    }
  }
}

​

Validation 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.

​

Precedence

1. System defaults
2. Tenant policy
3. defaultSearchConfig, if the search does not provide its own searchConfig
4. searchTypes[i].searchConfig, if provided

​

Field Reference

• Create Order
• VerificationRequestDto
• SearchTypeDto
• WebhookConfigDto