> ## 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. # Third-party ban > Configure searches so specific third-party verification vendors are never used. # Third-party ban Use `searchConfig.thirdPartyBan` when your organization does not want a search routed to specific third-party verification vendors. When a banned vendor is detected during research or inbound processing, SNH AI suppresses third-party routing for that vendor and continues with manual/outbound verification attempts. ## When to use it | Scenario | Use `thirdPartyBan`? | Why | | --------------------------------------------------------------------------------- | ------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Your client does not allow The Work Number for a specific search | Yes | Ban only `TALX_WORK_NUMBER` while leaving other vendors unchanged. | | Your client does not allow several known vendors for every search in an order | Yes | Put multiple vendor codes in `defaultSearchConfig.thirdPartyBan`. | | You want to suppress every third-party event, regardless of vendor | Prefer `escalation.disableThirdPartyEvent` | `thirdPartyBan` is vendor-specific. | | You want to ban an employer, school, routing id, or contact destination | No | Ban matching only applies to canonical third-party vendor codes. | | Research might pick vendor X, but the client must verify through vendor Y instead | Yes, plus a contact hint | Ban `X` in `thirdPartyBan` and seed `Y` in `outbound.contactHints[].thirdPartyVendor`. See [Use a different third-party instead](#use-a-different-third-party-instead). | ## Request shape | Location | Applies to | Notes | | ------------------------------------------- | --------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------- | | `defaultSearchConfig.thirdPartyBan` | Every search in the order that does not define its own `searchConfig` | Use for order-wide vendor restrictions. | | `searchTypes[i].searchConfig.thirdPartyBan` | One specific search | Fully replaces `defaultSearchConfig` for that search when `searchConfig` is present, even as `{}`. | Per-search `searchConfig` replaces `defaultSearchConfig` wholesale. If a search has its own `searchConfig`, include every search-level override that search needs inside that object. ## Field rules | Field | Type | Required | Rules | | --------------- | ---------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `thirdPartyBan` | `string[]` | No | Canonical vendor codes only. Max **50** entries. Values are trimmed, uppercased, and deduplicated. `UNKNOWN`, unknown codes, non-array values, and malformed values are rejected. Empty arrays are accepted and behave like omission. | ## Supported vendor codes These are the canonical values accepted by `thirdPartyBan`. ### Employment | Vendor code | Common names | | ------------------------- | ---------------------------------------------- | | `TALX_WORK_NUMBER` | TALX, The Work Number, INVerify, WNFE, Equifax | | `THOMAS_AND_COMPANY` | Thomas and Company, Thomas & Co | | `PRECHECK` | PreCheck, EmpCheck, EmployCheck | | `VERIFYTODAY` | VerifyToday, Verify Today System | | `CCCVERIFY` | CCC Verify, CCCVerify | | `EXPERIAN` | Experian Verify, uConfirm | | `QUICKCONFIRM` | QuickConfirm | | `ACT1` | ACT 1, ActOne | | `CERTREE_EMP` | Certree employment | | `DELTAT` | Delta-T Group | | `DRIVERIQ` | Driver IQ | | `EMERALD_HEALTH_SERVICES` | Emerald Health Services | | `EMPINFO` | EmpInfo | | `EVADVANTAGE` | EvAdvantage | | `GROUPONE` | GroupOne | | `TENSTREET` | Tenstreet | | `TRUECONFIRM` | TrueConfirm | | `TRUEWORK` | Truework, True Work | | `TRUV` | Truv | | `VAULT_VERIFY` | Vault Verify | | `VERIFENT` | Verifent | | `VERIFY_FAST` | Verify Fast, VerifyFast | | `VERIFY_ADVANTAGE` | VerifyAdvantage, VerifyDirect | | `VERISAFE_JOBS` | VeriSafe Jobs | | `VERIFICATION_MANAGER` | Verification Manager | | `JOBTRAX` | JobTrax | ### Education | Vendor code | Common names | | ------------------------ | ---------------------------------------------------------------- | | `NSCH` | National Student Clearinghouse, NSC, DegreeVerify, DiplomaVerify | | `NEED_MY_TRANSCRIPT` | Need My Transcript, NeedMyTranscript | | `PARCHMENT` | Parchment | | `SCRIBORDER` | ScribOrder | | `AURADATA` | AuraData | | `DIPLOMA_SENDER` | Diploma Sender | | `CERTREE_EDU` | Certree education | | `CHICAGO_PUBLIC_SCHOOLS` | Chicago Public Schools records portal | | `GRAMARCY` | Gramarcy, Gramercy | | `IEC` | IEC Corporation | | `INDIANA_ARCHIVES` | Indiana Archives | | `MERIDIAN_INSTITUTE` | Meridian Institute | | `OTTAWA_UNIVERSITY` | Ottawa University | | `TCSG` | Technical College System of Georgia | | `VERIF_Y_INC` | Verif-Y Inc. | `UNKNOWN` may appear in webhook metadata when a vendor could not be confidently recognized, but it is not accepted in `thirdPartyBan`. ## Examples ### Ban one vendor for one search ```json theme={null} { "searchTypes": [ { "searchType": "EMPLOYMENT", "searchConfig": { "thirdPartyBan": ["TALX_WORK_NUMBER"] } } ] } ``` ### Ban multiple vendors for all searches in an order ```json theme={null} { "defaultSearchConfig": { "thirdPartyBan": [ "TALX_WORK_NUMBER", "NSCH" ] }, "searchTypes": [ { "searchType": "EMPLOYMENT" }, { "searchType": "EDUCATION" } ] } ``` ### Use different bans per search ```json theme={null} { "searchTypes": [ { "searchType": "EMPLOYMENT", "searchConfig": { "thirdPartyBan": ["TALX_WORK_NUMBER", "TRUEWORK"] } }, { "searchType": "EDUCATION", "searchConfig": { "thirdPartyBan": ["NSCH", "PARCHMENT"] } } ] } ``` ### Combine ban with third-party deferral ```json theme={null} { "searchTypes": [ { "searchType": "EMPLOYMENT", "searchConfig": { "thirdPartyBan": ["TALX_WORK_NUMBER"], "outbound": { "thirdPartyDeferral": true, "thirdPartyDeferralHours": 72 } } } ] } ``` If `TALX_WORK_NUMBER` is detected, the ban wins immediately. No pending third-party timer is created, and no delayed third-party webhook is emitted later. ### Use a different third-party instead Use this pattern when research or inbound might surface one third-party vendor, but your client requires verification through a **different** service. Ban the vendor you do not want; seed the vendor you do want as a contact hint. | Step | What to set | Why | | ---- | ------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------ | | 1 | `thirdPartyBan: ["VENDOR_TO_AVOID"]` | Suppresses third-party routing and webhooks for that vendor when it is detected. Outbound and manual handling can continue. | | 2 | `outbound.contactHints[]` with `thirdPartyVendor: "VENDOR_TO_USE"` | Seeds the contact plan with your chosen vendor (`usesThirdParty=true`). Optional `thirdPartyCode` is the employer or school code at that vendor. | | 3 | Optional `research.skipResearch: true` | Skips automated discovery when you only want the hinted vendor and any direct destinations you list on the same hint. | `thirdPartyBan` and `contactHints[].thirdPartyVendor` must refer to **different** vendor codes. The API rejects a hint whose `thirdPartyVendor` also appears in `thirdPartyBan` for the same search — you cannot ban and seed the same vendor in one config. **Employment example:** block The Work Number if research finds it, but route through Truework with a known employer code. ```json theme={null} { "searchTypes": [ { "searchType": "EMPLOYMENT", "searchConfig": { "thirdPartyBan": ["TALX_WORK_NUMBER"], "outbound": { "contactHints": [ { "name": "Acme Corp", "thirdPartyVendor": "TRUEWORK", "thirdPartyCode": "ACME-EMP-001" } ] } } } ] } ``` **Education example:** block National Student Clearinghouse if it appears, but use Parchment with a school identifier. ```json theme={null} { "searchTypes": [ { "searchType": "EDUCATION", "searchConfig": { "thirdPartyBan": ["NSCH"], "outbound": { "contactHints": [ { "thirdPartyVendor": "PARCHMENT", "thirdPartyCode": "SCHOOL-ABC123" } ] } } } ] } ``` **Hints-only (no research):** when the client supplies the vendor up front and you do not want automated contact research to run. ```json theme={null} { "searchTypes": [ { "searchType": "EMPLOYMENT", "searchConfig": { "thirdPartyBan": ["TALX_WORK_NUMBER"], "research": { "skipResearch": true }, "outbound": { "contactHints": [ { "thirdPartyVendor": "VERIFYTODAY", "thirdPartyCode": "12345" } ] } } } ] } ``` At runtime: * If research or inbound detects a **banned** vendor, that vendor does not get third-party routing or a `THIRD_PARTY_RECORD` webhook; the search can still proceed on other contacts or on your hinted vendor. * The **hinted** vendor is merged into the contact plan per history item (deduplicated by vendor code and `thirdPartyCode`). It follows normal third-party precedence unless you set `escalation.disableThirdPartyEvent: true` to prefer direct channels on the same hint. * You may add `email`, `phone`, or `fax` on the same hint as a direct fallback alongside `thirdPartyVendor`. For field-level rules on `thirdPartyVendor` and `thirdPartyCode`, see [Search-level configuration](/guides/search-config-reference#seed-a-known-third-party-vendor) and [Search config](/api-reference/schemas/search-config). ### Normalization and deduping ```json theme={null} { "thirdPartyBan": [ " talx_work_number ", "TALX_WORK_NUMBER", "nsch" ] } ``` This resolves to `["TALX_WORK_NUMBER", "NSCH"]`. ## Runtime behavior | Flow | What happens when the detected vendor is banned | | ---------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Research finds a banned vendor | The third-party `verification.action_required` webhook is suppressed and manual or outbound handling continues. | | Third-party deferral is enabled | The ban takes precedence over deferral. The search is not queued for delayed third-party emission. | | Inbound redirects to a banned vendor | The search emits `verification.action_required` with `reasonCode: "HUMAN_ESCALATION"` and `metadata.escalationSubtype: "THIRD_PARTY_BAN"` instead of routing to the vendor. | | An unbanned or unrecognized vendor is detected | Existing third-party routing, deferral, and webhook behavior is preserved. | ## Webhook expectations When a vendor is banned, clients should not expect a `THIRD_PARTY_RECORD` action-required event for that vendor. For inbound redirects to a banned vendor, handle the human escalation event: ```json theme={null} { "type": "verification.action_required", "reasonCode": "HUMAN_ESCALATION", "metadata": { "escalationSubtype": "THIRD_PARTY_BAN", "vendor": "TALX_WORK_NUMBER" } } ``` ## Validation failures Invalid ban lists are rejected when the order is created. | Input | Result | | ------------------------------------- | -------------------------------------------------------- | | `"thirdPartyBan": "TALX_WORK_NUMBER"` | Rejected because the field must be an array. | | `"thirdPartyBan": ["UNKNOWN"]` | Rejected because `UNKNOWN` is not a supported ban value. | | `"thirdPartyBan": ["NOT_A_VENDOR"]` | Rejected because the code is not canonical. | | More than 50 entries | Rejected. | | `[]` or omitted | Accepted; no vendors are banned. | ## Related docs * [Search-level configuration](/guides/search-config-reference) * [Search config](/api-reference/schemas/search-config) * [Create order](/api-reference/endpoints/create-order) * [Webhook events](/webhooks/events#third-party-vendor-reference)