Verification request

Request body for creating a background check order. For a complete required / optional field table (top-level and nested objects), see Create order — Request body field reference.

Fields

Field	Required	Type	Description
`applicant`	Yes	`object`	Applicant identity and contact details. See Applicant.
`businessContext`	Yes	`object`	Role and hiring context for the requested verification. See Business context.
`searchTypes`	Yes	`object[]`	Searches to run. Supported values are `EMPLOYMENT` and `EDUCATION`. See Search type.
`history`	No	`object`	Employment and education records to verify. See History.
`defaultSearchConfig`	No	`object`	Order-level policy defaults for searches that do not define their own `searchConfig`. Supports channel, timing, outbound, research, inbound, escalation, notification, and `thirdPartyBan` overrides. See Search config.
`webhookConfig`	No	`object`	Per-order webhook routing and signing configuration. Takes precedence over organization-level webhook configuration. See Webhook config.

Nested shapes

`searchTypes[]`

[
  {
    "searchType": "EMPLOYMENT",
    "externalSearchId": "client-emp-001",
    "questionnaireUrl": "https://verify.example.com/form/abc123",
    "questionnaireAccessCode": "ACCESS123"
  },
  {
    "searchType": "EDUCATION",
    "searchConfig": {
      "thirdPartyBan": ["NSCH"]
    }
  }
]

`webhookConfig`

{
  "enabled": true,
  "secret": "webhook-secret-for-hmac-validation",
  "retryAttempts": 3,
  "closeoutEndpoints": {
    "EMPLOYMENT": "https://client.example.com/webhooks/employment-closeout",
    "EDUCATION": "https://client.example.com/webhooks/education-closeout"
  },
  "fallbackEndpoint": "https://client.example.com/webhooks/search-closeout"
}

Example

{
  "searchTypes": [
    {
      "searchType": "EMPLOYMENT",
      "externalSearchId": "client-emp-001",
      "questionnaireUrl": "https://verify.example.com/form/abc123",
      "questionnaireAccessCode": "ACCESS123"
    },
    {
      "searchType": "EDUCATION",
      "externalSearchId": "client-edu-001"
    }
  ],
  "applicant": {
    "firstName": "John",
    "lastName": "Smith",
    "ssn": "123-45-6789",
    "birthday": "1990-05-15",
    "phone": "+1-555-123-4567",
    "email": "john.smith@example.com",
    "signedReleaseFileUrl": "https://example.com/signed-release.pdf",
    "addresses": [
      {
        "addressType": "home",
        "addressLine1": "456 Oak Avenue",
        "addressLine2": null,
        "addressCity": "Los Angeles",
        "addressState": "CA",
        "addressZipCode": "90210",
        "addressCountry": "US",
        "startDate": "2021-01-01",
        "endDate": null
      }
    ],
    "applicantAlias": [
      {
        "firstName": "Jonathan",
        "lastName": "Smith",
        "middleName": "Michael",
        "suffix": "Jr."
      }
    ]
  },
  "businessContext": {
    "entityName": "Acme Corp",
    "appliedJobTitle": "Senior Software Engineer",
    "worksiteCity": "San Francisco",
    "worksiteState": "CA",
    "proposedSalary": 100000,
    "positionLevel": "STANDARD",
    "securityClearanceRequired": false,
    "industrySector": "TECHNOLOGY"
  },
  "history": {
    "employment": [
      {
        "employerName": "Tech Corp",
        "position": "Software Engineer",
        "employerEmail": "hr@techcorp.com",
        "employerPhone": "+1-555-123-4567",
        "startDate": "2020-01-15",
        "endDate": "2023-06-30"
      }
    ],
    "education": [
      {
        "institutionName": "University of California",
        "qualification": "Bachelor of Science in Computer Science",
        "fieldOfStudy": "Computer Science",
        "graduationDate": "2018-05-15",
        "institutionContactEmail": "registrar@berkeley.edu",
        "institutionContactPhone": "+1-510-642-6000"
      }
    ]
  },
  "webhookConfig": {
    "enabled": true,
    "secret": "webhook-secret-for-hmac-validation",
    "retryAttempts": 3,
    "closeoutEndpoints": {
      "EMPLOYMENT": [
        {
          "url": "https://client.example.com/webhooks/employment-closeout",
          "headers": { "X-Customer": "acme" },
          "events": ["verification.completed"]
        },
        {
          "url": "https://client.example.com/webhooks/employment-notifications",
          "events": ["verification.notification"]
        }
      ],
      "EDUCATION": [
        {
          "url": "https://client.example.com/webhooks/education-closeout",
          "basicAuth": { "username": "api", "password": "secret" },
          "events": ["verification.completed"]
        }
      ]
    },
    "fallbackEndpoint": [
      {
        "url": "https://client.example.com/webhooks/all-events",
        "events": ["verification.action_required"],
        "searchTypes": ["EMPLOYMENT", "EDUCATION"]
      }
    ]
  }
}

Validation rules

Date Format: All dates must be in YYYY-MM-DD format
Address Validation: Exactly one address must be current (endDate: null)
Email Validation: Must be valid email format
SSN: Required non-empty string. Conventionally XXX-XX-XXXX.

Applicant — Applicant information structure
Business context — Business context for the job position
History — Historical data for verification
Search type — Search type configuration
Search config — Per-search and order-level policy overrides
Webhook config — Webhook configuration structure

Overview

Orders API

Search Management

Batches API

Inbound API

Files API

Closeout Events API

Request and order schemas

Webhook schemas

Verification request

Verification request

Fields

Nested shapes

`searchTypes[]`

`webhookConfig`

Example

Validation rules

​Verification request

​Fields

​Nested shapes

​searchTypes[]

​webhookConfig

​Example

​Validation rules

​Related schemas

Verification request

Fields

Nested shapes

`searchTypes[]`

`webhookConfig`

Example

Validation rules

Related schemas