Skip to main content

​
Integration patterns

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

​
Pattern index

PatternUse when
Employment-onlyYou only need employment verification.
Education-onlyYou only need education verification.
Employment and education on one orderYou need both supported search types in one request.
Known contacts / skip broad researchYou already know the correct HR or registrar contact.
Ban third-party vendorsThe client does not want specific third-party vendors used.
Email-only outreachYou want to restrict outbound to email.
Manual reviewYou want inbound responses held for human review.
Per-search webhook routingYou 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. 
{
  "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

  1. GET /files/release-form/generate-upload-url → signedUrl, fileUri
  2. PUT PDF to signedUrl with Content-Type: application/pdf
  3. Set applicant.signedReleaseFileUrl to fileUri (gs://...)
Generate upload URL · Signed release file

​
Batch create caveats

POST /background-check/v1/batches accepts { "orders": [ ...VerificationRequestDto ] } 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. Not implemented: listing batches, fetching a batch by id, and deleting a batch return placeholder payloads; 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.