Third-party ban

Download this guide

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, Theary 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.

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
`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

{
  "searchTypes": [
    {
      "searchType": "EMPLOYMENT",
      "searchConfig": {
        "thirdPartyBan": ["TALX_WORK_NUMBER"]
      }
    }
  ]
}

Ban multiple vendors for all searches in an order

{
  "defaultSearchConfig": {
    "thirdPartyBan": [
      "TALX_WORK_NUMBER",
      "NSCH"
    ]
  },
  "searchTypes": [
    { "searchType": "EMPLOYMENT" },
    { "searchType": "EDUCATION" }
  ]
}

Use different bans per search

{
  "searchTypes": [
    {
      "searchType": "EMPLOYMENT",
      "searchConfig": {
        "thirdPartyBan": ["TALX_WORK_NUMBER", "TRUEWORK"]
      }
    },
    {
      "searchType": "EDUCATION",
      "searchConfig": {
        "thirdPartyBan": ["NSCH", "PARCHMENT"]
      }
    }
  ]
}

Combine ban with third-party deferral

{
  "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.

{
  "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.

{
  "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 Algolia or web research to run.

{
  "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 and SearchConfigDto.

Normalization and deduping

{
  "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, no `pendingThirdParty` timer is stored, outbound is not cancelled, an audit notation is recorded, and manual/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:

{
  "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.

Documentation Index

​Third-party ban

​When to use it

​Request shape

​Field rules

​Supported vendor codes

​Employment

​Education

​Examples

​Ban one vendor for one search

​Ban multiple vendors for all searches in an order

​Use different bans per search

​Combine ban with third-party deferral

​Use a different third-party instead

​Normalization and deduping

​Runtime behavior

​Webhook expectations

​Validation failures

​Related docs

Third-party ban

When to use it

Request shape

Field rules

Supported vendor codes

Employment

Education

Examples

Ban one vendor for one search

Ban multiple vendors for all searches in an order

Use different bans per search

Combine ban with third-party deferral

Use a different third-party instead

Normalization and deduping

Runtime behavior

Webhook expectations

Validation failures

Related docs