Create Order

Creates one background check order. Use sandbox to validate request shape and move the same contract to production with production credentials. Supported searchType values: EMPLOYMENT and EDUCATION.

Request body field reference

Top-level body

Field	Required	Type	Description
`applicant`	Yes	`object`	Person being verified (identity, optional contact, addresses, aliases). See Applicant.
`businessContext`	Yes	`object`	Hiring context for the role (employer, title, worksite, salary) — not the applicant home address. See Business context.
`searchTypes`	Yes	`object[]`	Searches to run. Values: `EMPLOYMENT	EDUCATION` only. At least one search is recommended. See Search type.
`history`	No	`object`	Employment and/or education records to verify. See History.
`webhookConfig`	No	`object`	Per-order webhook routing and signing; overrides organization-level webhook config. See Webhook config.
`defaultSearchConfig`	No	`object`	Order-level policy defaults (channels, outbound, timing, `thirdPartyBan`, etc.). Fully replaced per search when `searchTypes[].searchConfig` is set. See Search config.

`applicant`

Field	Required	Type	Description
`firstName`	Yes	`string`	Applicant legal first name. Example: `"John"`.
`lastName`	Yes	`string`	Applicant legal last name. Example: `"Smith"`.
`ssn`	Yes	`string`	Social Security Number. Conventionally `XXX-XX-XXXX` (example: `"123-45-6789"`). Required as a non-empty string; pattern is not API-enforced.
`birthday`	No	`string`	Date of birth in `YYYY-MM-DD` format. Example: `"1990-05-15"`.
`phone`	No	`string`	Applicant phone number for contact during verification. Example: `"+1-555-123-4567"`.
`email`	No	`string`	Applicant email address. Must be valid when provided.
`signedReleaseFileUrl`	No	`string`	Signed release PDF: HTTPS URL, `gs://` URI, or base64-encoded PDF (max 10MB). See Signed release file.
`addresses`	No	`object[]`	Optional address history. Omit or send `[]` when no home address is available. See Address.
`applicantAlias`	No	`object[]`	Alternate or former names (AKA). See Applicant alias.

`applicant.addresses[]` (when non-empty)

Field	Required	Type	Description
`addressType`	Yes	`string`	Address category. Convention for home history: `"home"`.
`addressLine1`	Yes	`string`	Street address line 1.
`addressLine2`	No	`string`	Apartment, suite, unit, or other secondary line.
`addressCity`	Yes	`string`	City.
`addressState`	Yes	`string`	Two-letter US state code. Example: `"CA"`.
`addressZipCode`	Yes	`string`	ZIP or postal code (1–10 characters).
`addressCountry`	No	`string`	Two-letter country code. Defaults to `US` when omitted.
`startDate`	Yes	`string`	Start of residence in `YYYY-MM-DD` format.
`endDate`	No	`string`	End of residence in `YYYY-MM-DD` format. `null` or omitted = current address. Exactly one entry must be current when the array is non-empty.

`applicant.applicantAlias[]`

Field	Required	Type	Description
`firstName`	Yes	`string`	Alias first name.
`lastName`	Yes	`string`	Alias last name.
`middleName`	No	`string`	Alias middle name.
`suffix`	No	`string`	Name suffix such as `Jr.`, `Sr.`, or `III`.

`businessContext`

Field	Required	Type	Description
`entityName`	Yes	`string`	Employer the candidate is applying to. Example: `"Acme Corp"`.
`appliedJobTitle`	Yes	`string`	Job title the candidate is applying for. Example: `"Senior Software Engineer"`.
`worksiteCity`	Yes	`string`	City of the proposed worksite (not applicant home). Example: `"San Francisco"`.
`worksiteState`	Yes	`string`	Two-letter state code for the proposed worksite. Example: `"CA"`.
`proposedSalary`	Yes	`number`	Proposed salary as a number. Example: `100000`.
`positionLevel`	No	`string`	Common values: `EXECUTIVE`, `STANDARD`, `SENSITIVE` (not enum-enforced).
`securityClearanceRequired`	No	`boolean`	Whether the role requires security clearance.
`industrySector`	No	`string`	Industry sector for regulatory context. Example: `"TECHNOLOGY"`.

`searchTypes[]`

Field	Required	Type	Description
`searchType`	Yes	`string`	Search type to run: `EMPLOYMENT` or `EDUCATION`.
`externalSearchId`	No	`string`	Client correlation ID for webhook idempotency and reconciliation.
`questionnaireUrl`	No	`string`	Optional direct link to the online questionnaire for this search.
`questionnaireAccessCode`	No	`string`	Optional access code for the online questionnaire.
`verificationQuestions`	No	`object[]`	Custom questions (max 50). Types include `multi_select`; optional `condition`, `minSelections` / `maxSelections`. See Verification question.
`searchConfig`	No	`object`	Per-search policy overrides. When present (even as `{}`), fully replaces `defaultSearchConfig` for this search. See Search config.

Search policy fields

Use defaultSearchConfig for order-wide defaults, or searchTypes[].searchConfig for one search. See Search config for the full nested table.

Field	Type	Description
`thirdPartyBan`	`string[]`	Canonical vendor codes to suppress for this search, such as `TALX_WORK_NUMBER` or `NSCH`. Max 50; `UNKNOWN` is rejected. See Third-party ban.
`channels`	`object`	Channel enablement, preferred channel, allowed destinations, and blocked destinations.
`timing`	`object`	SLA, outbound window, and business-hours overrides.
`outbound`	`object`	Attempt caps, third-party deferral, terminal-inbound outbound cancel, and `contactHints`.
`research`	`object`	Research controls such as `skipResearch`.
`inbound`	`object`	Manual-review and auto-complete behavior for inbound responses.
`escalation`	`object`	Auto-escalation, escalation webhook URL, and broad third-party event suppression.
`notifications`	`object`	Notification suppression, raw inbound inclusion, and webhook override routing.
`qaDestinations`	`object`	Non-production only. Redirect this search’s outbound to test email/phone/fax. Validated in every environment, ignored in production. See Search config.

`history`

Field	Required	Type	Description
`employment`	No	`object[]`	Employment records to verify. See Employment history.
`education`	No	`object[]`	Education records to verify. See Education history.

`history.employment[]`

Field	Required	Type	Description
`employerName`	Yes	`string`	Employer or company name. Example: `"Tech Corp"`.
`position`	Yes	`string`	Job title held. Example: `"Software Engineer"`.
`employerLocation`	No	`string`	Work location. Example: `"San Francisco, CA"`.
`employerEmail`	No	`string`	Employer contact email for verification. Must be valid when provided.
`employerPhone`	No	`string`	Employer contact phone for verification.
`employerFax`	No	`string`	Employer contact fax for verification.
`startDate`	No	`string`	Employment start date in `YYYY-MM-DD` format.
`endDate`	No	`string`	Employment end date in `YYYY-MM-DD` format. Omit or `null` for current job.

`history.education[]`

Field	Required	Type	Description
`institutionName`	Yes	`string`	Educational institution name. Example: `"University of California"`.
`qualification`	Yes	`string`	Credential earned. Example: `"Bachelor of Science in Computer Science"`.
`fieldOfStudy`	Yes	`string`	Major or field of study. Example: `"Computer Science"`.
`institutionLocation`	No	`string`	Institution location. Example: `"Berkeley, CA"`.
`startDate`	No	`string`	Attendance start date in `YYYY-MM-DD` format.
`endDate`	No	`string`	Attendance end date in `YYYY-MM-DD` format (use when the applicant attended but did not graduate).
`graduationDate`	No	`string`	Graduation or completion date in `YYYY-MM-DD` format. Optional if the applicant did not graduate.
`institutionContactEmail`	No	`string`	Institution contact email for verification. Must be valid when provided.
`institutionContactPhone`	No	`string`	Institution contact phone for verification.

Field validation notes

Field	Constraint
`applicant.ssn`	Required, non-empty string. The API accepts any non-empty value (no pattern enforcement). Conventionally `XXX-XX-XXXX`.
`businessContext.positionLevel`	Free-text string. Common values are `EXECUTIVE`, `STANDARD`, `SENSITIVE`, but the API does not enforce an enum. Use consistent values across your integration for downstream reporting.
`businessContext.industrySector`	Free-text string. Examples: `TECHNOLOGY`, `HEALTHCARE`, `FINANCE`. Not enum-enforced.
`businessContext.proposedSalary`	Must be a number (`100000`, not `"100000"`).
`webhookConfig.retryAttempts`	Integer. Default: `3`. Maximum: `10`. Values outside this range may produce unexpected behavior.
All date fields	`YYYY-MM-DD` format. Invalid formats return `400`.

Conditional requirements

applicant.addresses is optional. Employment and education verification use businessContext.worksite* and history locations, not home address.
If addresses is non-empty: exactly one current address (endDate: null or omitted); startDate must be before endDate on historical rows.
Do not send addresses: [{}] — omit the field instead of sending partial address objects.

Minimal example (no home address)

{
  "searchTypes": [{ "searchType": "EMPLOYMENT" }],
  "applicant": {
    "firstName": "John",
    "lastName": "Smith",
    "ssn": "123-45-6789"
  },
  "businessContext": {
    "entityName": "Acme Corp",
    "appliedJobTitle": "Senior Software Engineer",
    "worksiteCity": "San Francisco",
    "worksiteState": "CA",
    "proposedSalary": 100000
  },
  "history": {
    "employment": [
      {
        "employerName": "Tech Corp",
        "position": "Software Engineer",
        "employerLocation": "San Francisco, CA",
        "startDate": "2020-01-15",
        "endDate": "2023-06-30"
      }
    ]
  }
}

Full example (with home address)

Use this JSON body to create a single employment verification order with optional applicant home address.

{
  "searchTypes": [
    {
      "searchType": "EMPLOYMENT",
      "externalSearchId": "client-emp-001",
      "questionnaireUrl": "https://verify.example.com/form/abc123",
      "questionnaireAccessCode": "ACCESS123"
    }
  ],
  "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",
        "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",
        "employerLocation": "San Francisco, CA",
        "employerEmail": "hr@techcorp.com",
        "employerPhone": "+1-555-123-4567",
        "employerFax": "+1-555-987-6543",
        "startDate": "2020-01-15",
        "endDate": "2023-06-30"
      }
    ]
  },
  "webhookConfig": {
    "enabled": true,
    "secret": "webhook-secret-for-hmac-validation",
    "retryAttempts": 3,
    "fallbackEndpoint": "https://your-app.com/webhooks/verification"
  }
}

Example request

Replace YOUR_JWT_TOKEN with a sandbox Bearer JWT that includes your organization’s tenant claim. The body below is the minimal employment example; swap in the full example when you need addresses, aliases, or webhooks.

curl -sS -X POST "https://sandbox.theary.ai/background-check/v1/orders" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "searchTypes": [{ "searchType": "EMPLOYMENT" }],
    "applicant": {
      "firstName": "John",
      "lastName": "Smith",
      "ssn": "123-45-6789"
    },
    "businessContext": {
      "entityName": "Acme Corp",
      "appliedJobTitle": "Senior Software Engineer",
      "worksiteCity": "San Francisco",
      "worksiteState": "CA",
      "proposedSalary": 100000
    },
    "history": {
      "employment": [
        {
          "employerName": "Tech Corp",
          "position": "Software Engineer",
          "employerLocation": "San Francisco, CA",
          "startDate": "2020-01-15",
          "endDate": "2023-06-30"
        }
      ]
    }
  }'

# Save the minimal or full JSON example as order.json, then:
curl -sS -X POST "https://sandbox.theary.ai/background-check/v1/orders" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  --data @order.json

const response = await fetch('https://sandbox.theary.ai/background-check/v1/orders', {
  method: 'POST',
  headers: {
    Authorization: 'Bearer YOUR_JWT_TOKEN',
    'Content-Type': 'application/json',
    Accept: 'application/json',
  },
  body: JSON.stringify({
    searchTypes: [{ searchType: 'EMPLOYMENT' }],
    applicant: {
      firstName: 'John',
      lastName: 'Smith',
      ssn: '123-45-6789',
    },
    businessContext: {
      entityName: 'Acme Corp',
      appliedJobTitle: 'Senior Software Engineer',
      worksiteCity: 'San Francisco',
      worksiteState: 'CA',
      proposedSalary: 100000,
    },
    history: {
      employment: [
        {
          employerName: 'Tech Corp',
          position: 'Software Engineer',
          employerLocation: 'San Francisco, CA',
          startDate: '2020-01-15',
          endDate: '2023-06-30',
        },
      ],
    },
  }),
})

if (!response.ok) {
  throw new Error(`Create order failed: ${response.status} ${await response.text()}`)
}

const { verificationOrderId, searchIds } = await response.json()

import requests

payload = {
    "searchTypes": [{"searchType": "EMPLOYMENT"}],
    "applicant": {
        "firstName": "John",
        "lastName": "Smith",
        "ssn": "123-45-6789",
    },
    "businessContext": {
        "entityName": "Acme Corp",
        "appliedJobTitle": "Senior Software Engineer",
        "worksiteCity": "San Francisco",
        "worksiteState": "CA",
        "proposedSalary": 100000,
    },
    "history": {
        "employment": [
            {
                "employerName": "Tech Corp",
                "position": "Software Engineer",
                "employerLocation": "San Francisco, CA",
                "startDate": "2020-01-15",
                "endDate": "2023-06-30",
            }
        ]
    },
}

response = requests.post(
    "https://sandbox.theary.ai/background-check/v1/orders",
    headers={
        "Authorization": "Bearer YOUR_JWT_TOKEN",
        "Content-Type": "application/json",
        "Accept": "application/json",
    },
    json=payload,
    timeout=30,
)
response.raise_for_status()
data = response.json()
verification_order_id = data["verificationOrderId"]
search_ids = data["searchIds"]

Optional search policy override

Use defaultSearchConfig for order-wide defaults. Add searchConfig inside a searchTypes[] entry only when that search needs different behavior; per-search config replaces the order default for that search.

{
  "defaultSearchConfig": {
    "thirdPartyBan": ["TALX_WORK_NUMBER"],
    "channels": {
      "email": true,
      "voice": true,
      "fax": false,
      "preferredChannel": "EMAIL"
    },
    "outbound": {
      "maxAttemptsPerMethod": 3,
      "maxTotalAttempts": 8
    }
  },
  "searchTypes": [
    {
      "searchType": "EMPLOYMENT",
      "searchConfig": {
        "thirdPartyBan": ["TALX_WORK_NUMBER", "TRUEWORK"],
        "channels": {
          "email": true,
          "voice": false,
          "fax": false,
          "preferredChannel": "EMAIL"
        },
        "outbound": {
          "contactHints": [
            { "email": "hr@techcorp.com", "priority": "HIGH" }
          ]
        }
      }
    }
  ]
}

For client-specific third-party restrictions, see Third-party ban for supported vendor codes, multiple-value examples, and deferral behavior.

Example response

{
  "verificationOrderId": "123e4567-e89b-12d3-a456-426614174000",
  "searchIds": ["456e7890-e89b-12d3-a456-426614174001"]
}

Next, prefer webhooks for completion. To poll results, call Get order searches (not Get order — that returns order status only, without verification outcomes).

Error responses

Status	When
`400`	Validation failed (invalid field shapes or unsupported values).
`401`	Missing or invalid Bearer JWT, or JWT missing the `tenant` claim.

{
  "statusCode": 400,
  "message": ["searchType must be EMPLOYMENT or EDUCATION"],
  "error": "Bad Request"
}

{
  "statusCode": 401,
  "message": "Unauthorized"
}

Body

application/json

applicant

object

required

Applicant details. Within applicant, addresses and aliases are arrays to capture history over time.

Show child attributes

Example:

{
  "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
    },
    {
      "addressType": "home",
      "addressLine1": "123 Main Street",
      "addressLine2": "Apt 4B",
      "addressCity": "New York",
      "addressState": "NY",
      "addressZipCode": "10001",
      "addressCountry": "US",
      "startDate": "2020-01-01",
      "endDate": "2021-01-01"
    }
  ],
  "applicantAlias": [
    {
      "firstName": "Jonathan",
      "lastName": "Smith",
      "middleName": "Michael",
      "suffix": "Jr."
    }
  ]
}

businessContext

object

required

Business context for the new job position the applicant is applying for

Show child attributes

Example:

{
  "entityName": "Apple",
  "appliedJobTitle": "Senior Software Engineer",
  "worksiteCity": "San Francisco",
  "worksiteState": "CA",
  "proposedSalary": 100000,
  "positionLevel": "STANDARD",
  "securityClearanceRequired": false,
  "industrySector": "TECHNOLOGY"
}

searchTypes

object[]

required

Search types to create for this verification order

Show child attributes

Example:

[
  {
    "searchType": "EMPLOYMENT",
    "externalSearchId": "12345678",
    "questionnaireUrl": "https://verify.example.com/form/abc123",
    "questionnaireAccessCode": "ACCESS123",
    "verificationQuestions": [
      {
        "questionId": 100001,
        "type": "single_select",
        "prompt": "Would you rehire this candidate?",
        "required": true,
        "options": [
          { "value": "yes", "label": "Yes" },
          { "value": "no", "label": "No" }
        ],
        "allowComment": true,
        "selectedAnswer": null,
        "comment": null
      },
      {
        "questionId": 100002,
        "type": "multi_select",
        "prompt": "Which skills apply?",
        "required": true,
        "options": [
          { "value": "a", "label": "A" },
          { "value": "b", "label": "B" }
        ],
        "minSelections": 1,
        "maxSelections": 2,
        "selectedAnswer": null,
        "comment": null
      },
      {
        "questionId": 100003,
        "type": "free_text",
        "prompt": "What were the candidate strengths?",
        "required": false,
        "allowComment": false,
        "condition": {
          "dependsOn": 700001,
          "operator": "equals",
          "values": ["No"]
        },
        "selectedAnswer": null,
        "comment": null
      }
    ]
  }
]

history

object

Historical data for verification including employment and education records

Show child attributes

Example:

{
  "employment": [
    {
      "employerName": "Tech Corp",
      "position": "Software Engineer",
      "employerLocation": "San Francisco, CA",
      "employerEmail": "hr@techcorp.com",
      "employerPhone": "+1-555-123-4567",
      "startDate": "2020-01-15",
      "endDate": "2023-06-30"
    }
  ]
}

webhookConfig

object

Optional webhook configuration for this verification request. Takes precedence over tenant-level webhook configuration.

Show child attributes

Example:

{
  "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"]
    }
  ]
}

defaultSearchConfig

object

Order-level default searchConfig applied to every created search whose searchTypes[i].searchConfig is absent. Per-search searchConfig WHOLESALE REPLACES this default when present (even as an empty object).

Show child attributes

Example:

{
  "channels": {
    "email": true,
    "voice": false,
    "preferredChannel": "EMAIL",
    "blockedDestinations": ["hr-noreply@company.com"]
  },
  "timing": {
    "searchSlaMinutes": 2880,
    "outboundWindowMinutes": 120,
    "businessHours": {
      "timezone": "America/Chicago",
      "startTime": "09:00",
      "endTime": "16:00",
      "allowedDays": [1, 2, 3, 4, 5]
    }
  },
  "outbound": {
    "maxAttemptsPerMethod": 5,
    "maxTotalAttempts": 12,
    "cancelOutboundOnTerminalInbound": true,
    "contactHints": [
      {
        "email": "hr@company.com",
        "priority": "HIGH"
      }
    ]
  },
  "research": { "skipResearch": false }
}

Response

201 - application/json

The response is of type object.

Overview

Orders API

Search Management

Batches API

Inbound API

Files API

Closeout Events API

Request and order schemas

Webhook schemas

Create Order

Create Order

Request body field reference

Top-level body

`applicant`

`applicant.addresses[]` (when non-empty)

`applicant.applicantAlias[]`

`businessContext`

`searchTypes[]`

Search policy fields

`history`

`history.employment[]`

`history.education[]`

Field validation notes

Conditional requirements

Minimal example (no home address)

Full example (with home address)

Example request

Optional search policy override

Example response

Error responses

Body

Response

​Create Order

​Request body field reference

​Top-level body

​applicant

​applicant.addresses[] (when non-empty)

​applicant.applicantAlias[]

​businessContext

​searchTypes[]

​Search policy fields

​history

​history.employment[]

​history.education[]

​Field validation notes

​Conditional requirements

​Minimal example (no home address)

​Full example (with home address)

​Example request

​Optional search policy override

​Example response

​Error responses

Body

Response

Create Order

Request body field reference

Top-level body

`applicant`

`applicant.addresses[]` (when non-empty)

`applicant.applicantAlias[]`

`businessContext`

`searchTypes[]`

Search policy fields

`history`

`history.employment[]`

`history.education[]`

Field validation notes

Conditional requirements

Minimal example (no home address)

Full example (with home address)

Example request

Optional search policy override

Example response

Error responses