Examples

Download this guide

Each snippet focuses on the differing parts of a Create order request. Combine with full field requirements from Applicant, Business context, History, and Verification request.

Pattern index

Pattern	Use when
Employment-only	You only need employment verification.
Education-only	You only need education verification.
Employment and education on one order	You need both supported search types in one request.
Known contacts / skip broad research	You already know the correct HR or registrar contact.
Ban third-party vendors	The client does not want specific third-party vendors used.
Email-only outreach	You want to restrict outbound to email.
Manual review	You want inbound responses held for human review.
Per-search webhook routing	You need event routing that differs by search type or target.

Employment-only

{
  "applicant": { "...": "..." },
  "businessContext": {
    "entityName": "Acme Corp",
    "appliedJobTitle": "Engineer",
    "worksiteCity": "Austin",
    "worksiteState": "TX",
    "proposedSalary": 120000
  },
  "searchTypes": [{ "searchType": "EMPLOYMENT" }],
  "history": {
    "employment": [
      {
        "employerName": "Acme Corp",
        "position": "Engineer",
        "startDate": "2020-01-01",
        "endDate": "2023-06-30"
      }
    ]
  }
}

Education-only

{
  "applicant": { "...": "..." },
  "businessContext": {
    "entityName": "State University",
    "appliedJobTitle": "Research Assistant",
    "proposedSalary": 0
  },
  "searchTypes": [{ "searchType": "EDUCATION" }],
  "history": {
    "education": [
      {
        "institutionName": "State University",
        "qualification": "BS Computer Science",
        "fieldOfStudy": "CS",
        "graduationDate": "2018-05-15",
        "institutionContactEmail": "registrar@example.edu"
      }
    ]
  }
}

Employment and education on one order

{
  "searchTypes": [{ "searchType": "EMPLOYMENT" }, { "searchType": "EDUCATION" }],
  "history": {
    "employment": [{ "...": "..." }],
    "education": [{ "...": "..." }]
  }
}

(Include complete applicant and businessContext as for a single-type order.)

Known contacts / skip broad research

Use defaultSearchConfig or per-search searchConfig with research.skipResearch: true and seed outbound.contactHints. See Search config.

{
  "defaultSearchConfig": {
    "research": { "skipResearch": true },
    "outbound": {
      "contactHints": [{ "email": "hr@employer.com", "priority": "HIGH" }]
    }
  }
}

Ban third-party vendors

Use thirdPartyBan when a client does not want searches routed to specific third-party providers. Values are canonical vendor codes; see Third-party ban for the full supported list.

Ban one vendor for one search

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

Ban multiple vendors order-wide

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

Ban wins over third-party deferral

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

When a banned vendor is detected, third-party routing is suppressed and manual/outbound handling continues.

Email-only outreach

{
  "defaultSearchConfig": {
    "channels": {
      "email": true,
      "voice": false,
      "fax": false,
      "preferredChannel": "EMAIL"
    }
  }
}

Manual review (inbound)

{
  "searchTypes": [
    {
      "searchType": "EMPLOYMENT",
      "searchConfig": { "inbound": { "requireManualReview": true } }
    }
  ]
}

Per-search webhook routing

Use WebhookTarget objects under closeoutEndpoints and fallbackEndpoint (string URL, single object, or array). Example: send employment closeouts to one URL and everything else to a fallback:

{
  "webhookConfig": {
    "enabled": true,
    "secret": "shared-or-per-target-secret",
    "closeoutEndpoints": {
      "EMPLOYMENT": [
        {
          "url": "https://client.example/webhooks/employment",
          "events": ["verification.completed", "verification.notification"]
        }
      ]
    },
    "fallbackEndpoint": [
      {
        "url": "https://client.example/webhooks/other",
        "events": ["verification.action_required", "verification.notification"],
        "searchTypes": ["EDUCATION"]
      }
    ]
  }
}

Release-form upload

Provide a signed release PDF in applicant.signedReleaseFileUrl using one of:

HTTPS URL — host the PDF at a stable public URL
GCS upload (recommended for larger files) — presigned upload flow below
Inline base64 — raw base64 or data:application/pdf;base64,... (max 10MB); uploaded to cloud storage at order creation

GCS upload flow

GET /files/release-form/generate-upload-url → signedUrl, fileUri
PUT PDF to signedUrl with Content-Type: application/pdf
Set applicant.signedReleaseFileUrl to fileUri (gs://...)

Generate upload URL · Signed release file

Batch create caveats

POST /background-check/v1/batches accepts { "orders": [ ...Verification request ] } and creates each order in parallel via the same path as single-order creation. The response includes a synthetic batchId and per-order verificationOrderId / searchIds in orders. Validation / creation errors: if any order fails validation or throws during createOrder, the whole HTTP request fails with an error (you do not get a 200 with mixed success/failure). Partial success risk: if the server fails after some orders were created (timeout, connection drop), you can be left with some orders already persisted. Persist every returned verificationOrderId as soon as you receive the response and reconcile with List orders. Order tracking: batch create returns per-order IDs only; track orders with List orders, Get order, and Get order searches.

Webhook idempotency

Deliveries may retry. Deduplicate with the X-Event-Id header (unique per delivery) and your own externalSearchId when you set it on searches. Acknowledge with a 2xx response; see Webhook events and Webhook integration.

Core concepts

Guides

Examples

Troubleshooting

Examples

Examples

Pattern index

Employment-only

Education-only

Employment and education on one order

Known contacts / skip broad research

Ban third-party vendors

Ban one vendor for one search

Ban multiple vendors order-wide

Ban wins over third-party deferral

Email-only outreach

Manual review (inbound)

Per-search webhook routing

Release-form upload

GCS upload flow

Batch create caveats

Webhook idempotency

​Examples

​Pattern index

​Employment-only

​Education-only

​Employment and education on one order

​Known contacts / skip broad research

​Ban third-party vendors

​Ban one vendor for one search

​Ban multiple vendors order-wide

​Ban wins over third-party deferral

​Email-only outreach

​Manual review (inbound)

​Per-search webhook routing

​Release-form upload

​GCS upload flow

​Batch create caveats

​Webhook idempotency

Examples

Pattern index

Employment-only

Education-only

Employment and education on one order

Known contacts / skip broad research

Ban third-party vendors

Ban one vendor for one search

Ban multiple vendors order-wide

Ban wins over third-party deferral

Email-only outreach

Manual review (inbound)

Per-search webhook routing

Release-form upload

GCS upload flow

Batch create caveats

Webhook idempotency