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 only. CRIMINAL, REFERENCE, criminalCheck, and history.criminal are not accepted.

Request body field reference

Top-level body

Field	Required	Type	Notes
`applicant`	Yes	object	See Applicant.
`businessContext`	Yes	object	Proposed job / worksite (not applicant home address). See BusinessContext.
`searchTypes`	Yes	array	At least one search recommended. Values: `EMPLOYMENT` or `EDUCATION` only.
`history`	No	object	Employment and/or education records to verify.
`webhookConfig`	No	object	Per-order webhook overrides.
`defaultSearchConfig`	No	object	Order-level policy defaults, including channel, outbound, timing, and third-party ban overrides. Replaced per-search when `searchTypes[].searchConfig` is set.

`applicant`

Field	Required	Type	Notes
`firstName`	Yes	string
`lastName`	Yes	string
`ssn`	Yes	string	`XXX-XX-XXXX` format.
`birthday`	No	string	`YYYY-MM-DD`
`phone`	No	string
`email`	No	string	Valid email if provided.
`signedReleaseFileUrl`	No	string	HTTPS URL, `gs://` URI, or base64-encoded PDF (max 10MB). See Signed release file.
`addresses`	No	array	Optional. Omit or send `[]` for no home address.
`applicantAlias`	No	array	Alternate names.

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

Field	Required	Type	Notes
`addressType`	Yes	string	Convention: `"home"`.
`addressLine1`	Yes	string
`addressLine2`	No	string
`addressCity`	Yes	string
`addressState`	Yes	string	2-letter US state code.
`addressZipCode`	Yes	string	1–10 characters.
`addressCountry`	No	string	2-letter code; defaults to `US`.
`startDate`	Yes	string	`YYYY-MM-DD`
`endDate`	No	string	`null` or omitted = current address. Exactly one entry must be current when the array is non-empty.

`businessContext`

Field	Required	Type	Notes
`entityName`	Yes	string	Employer the candidate applies to.
`appliedJobTitle`	Yes	string
`worksiteCity`	Yes	string	Proposed job location (not applicant home).
`worksiteState`	Yes	string	2-letter state code.
`proposedSalary`	Yes	number
`positionLevel`	No	string	e.g. `EXECUTIVE`, `STANDARD`, `SENSITIVE`
`securityClearanceRequired`	No	boolean
`industrySector`	No	string

`searchTypes[]`

Field	Required	Type	Notes
`searchType`	Yes	enum	`EMPLOYMENT` or `EDUCATION`
`externalSearchId`	No	string	Client correlation ID.
`questionnaireUrl`	No	string
`questionnaireAccessCode`	No	string
`searchConfig`	No	object	Per-search policy overrides. Replaces `defaultSearchConfig` for this search when present (even `{}`).

Search policy fields

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

Field	Type	Notes
`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.

`history`

Field	Required	Type	Notes
`employment`	No	array	See employment history table.
`education`	No	array	See education history table.

`history.employment[]`

Field	Required	Type	Notes
`employerName`	Yes	string
`position`	Yes	string
`employerLocation`	No	string
`employerEmail`	No	string
`employerPhone`	No	string
`employerFax`	No	string
`startDate`	No	string	`YYYY-MM-DD`
`endDate`	No	string	Omit/null for current job.

`history.education[]`

Field	Required	Type
`institutionName`	Yes	string
`qualification`	Yes	string
`fieldOfStudy`	Yes	string
`institutionLocation`	No	string
`startDate`	No	string
`endDate`	No	string
`graduationDate`	No	string
`institutionContactEmail`	No	string
`institutionContactPhone`	No	string

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.
criminalCheck and history.criminal return 400 if present in the request body.

Minimal example (no home address)

{
  "searchTypes": [{ "searchType": "EMPLOYMENT" }],
  "applicant": {
    "firstName": "John",
    "lastName": "Smith",
    "ssn": "123-45-6789"
  },
  "businessContext": {
    "entityName": "Apple",
    "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"
    }
  ],
  "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
      }
    ]
  },
  "businessContext": {
    "entityName": "Apple",
    "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",
        "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"
  }
}

cURL

Save the JSON above as order.json, then:

curl -X POST "https://sandbox.theary.com/background-check/v1/orders" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  --data @order.json

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.

Response

{
  "verificationOrderId": "ord_123e4567-e89b-12d3-a456-426614174000",
  "searchIds": ["search_456e7890-e89b-12d3-a456-426614174001"]
}

Next, call Get order searches or rely on webhooks.

Error responses

400 Bad Request

{
  "statusCode": 400,
  "message": ["searchTypes must not be empty"],
  "error": "Bad Request"
}

401 Unauthorized

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

​Create Order

​Request body field reference

​Top-level body

​applicant

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

​businessContext

​searchTypes[]

​Search policy fields

​history

​history.employment[]

​history.education[]

​Conditional requirements

​Minimal example (no home address)

​Full example (with home address)

​cURL

​Optional search policy override

​Response

​Error responses