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

# Verification request

> Request body schema for creating background check orders.

# 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](/api-reference/endpoints/create-order#request-body-field-reference).

## Fields

| Field                 | Required | Type       | Description                                                                                                                                                                                                                                                      |
| --------------------- | -------- | ---------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `applicant`           | Yes      | `object`   | Applicant identity and contact details. See [Applicant](/api-reference/schemas/applicant).                                                                                                                                                                       |
| `businessContext`     | Yes      | `object`   | Role and hiring context for the requested verification. See [Business context](/api-reference/schemas/business-context).                                                                                                                                         |
| `searchTypes`         | Yes      | `object[]` | Searches to run. Supported values are `EMPLOYMENT` and `EDUCATION`. See [Search type](/api-reference/schemas/search-type).                                                                                                                                       |
| `history`             | No       | `object`   | Employment and education records to verify. See [History](/api-reference/schemas/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](/api-reference/schemas/search-config). |
| `webhookConfig`       | No       | `object`   | Per-order webhook routing and signing configuration. Takes precedence over organization-level webhook configuration. See [Webhook config](/api-reference/schemas/webhook-config).                                                                                |

## Nested shapes

### `searchTypes[]`

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

### `webhookConfig`

```json theme={null}
{
  "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

```json theme={null}
{
  "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`.

## Related schemas

* [Applicant](/api-reference/schemas/applicant) — Applicant information structure
* [Business context](/api-reference/schemas/business-context) — Business context for the job position
* [History](/api-reference/schemas/history) — Historical data for verification
* [Search type](/api-reference/schemas/search-type) — Search type configuration
* [Search config](/api-reference/schemas/search-config) — Per-search and order-level policy overrides
* [Webhook config](/api-reference/schemas/webhook-config) — Webhook configuration structure