Create single verification order
curl --request POST \
--url https://sandbox.theary.ai/background-check/v1/orders \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"searchTypes": [
{
"searchType": "EMPLOYMENT",
"externalSearchId": "12345678",
"questionnaireUrl": "https://verify.example.com/form/abc123",
"questionnaireAccessCode": "ACCESS123",
"searchConfig": {
"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
}
}
}
],
"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
},
{
"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": {
"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",
"startDate": "2020-01-15",
"endDate": "2023-06-30"
}
]
}
}
'import requests
url = "https://sandbox.theary.ai/background-check/v1/orders"
payload = {
"searchTypes": [
{
"searchType": "EMPLOYMENT",
"externalSearchId": "12345678",
"questionnaireUrl": "https://verify.example.com/form/abc123",
"questionnaireAccessCode": "ACCESS123",
"searchConfig": {
"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 }
}
}
],
"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": None,
"addressCity": "Los Angeles",
"addressState": "CA",
"addressZipCode": "90210",
"addressCountry": "US",
"startDate": "2021-01-01",
"endDate": None
},
{
"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": {
"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",
"startDate": "2020-01-15",
"endDate": "2023-06-30"
}
] }
}
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({
searchTypes: [
{
searchType: 'EMPLOYMENT',
externalSearchId: '12345678',
questionnaireUrl: 'https://verify.example.com/form/abc123',
questionnaireAccessCode: 'ACCESS123',
searchConfig: {
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}
}
}
],
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
},
{
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: {
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',
startDate: '2020-01-15',
endDate: '2023-06-30'
}
]
}
})
};
fetch('https://sandbox.theary.ai/background-check/v1/orders', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://sandbox.theary.ai/background-check/v1/orders",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'searchTypes' => [
[
'searchType' => 'EMPLOYMENT',
'externalSearchId' => '12345678',
'questionnaireUrl' => 'https://verify.example.com/form/abc123',
'questionnaireAccessCode' => 'ACCESS123',
'searchConfig' => [
'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
]
]
]
],
'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
],
[
'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' => [
'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',
'startDate' => '2020-01-15',
'endDate' => '2023-06-30'
]
]
]
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"Content-Type: application/json"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://sandbox.theary.ai/background-check/v1/orders"
payload := strings.NewReader("{\n \"searchTypes\": [\n {\n \"searchType\": \"EMPLOYMENT\",\n \"externalSearchId\": \"12345678\",\n \"questionnaireUrl\": \"https://verify.example.com/form/abc123\",\n \"questionnaireAccessCode\": \"ACCESS123\",\n \"searchConfig\": {\n \"channels\": {\n \"email\": true,\n \"voice\": false,\n \"preferredChannel\": \"EMAIL\",\n \"blockedDestinations\": [\n \"hr-noreply@company.com\"\n ]\n },\n \"timing\": {\n \"searchSlaMinutes\": 2880,\n \"outboundWindowMinutes\": 120,\n \"businessHours\": {\n \"timezone\": \"America/Chicago\",\n \"startTime\": \"09:00\",\n \"endTime\": \"16:00\",\n \"allowedDays\": [\n 1,\n 2,\n 3,\n 4,\n 5\n ]\n }\n },\n \"outbound\": {\n \"maxAttemptsPerMethod\": 5,\n \"maxTotalAttempts\": 12,\n \"cancelOutboundOnTerminalInbound\": true,\n \"contactHints\": [\n {\n \"email\": \"hr@company.com\",\n \"priority\": \"HIGH\"\n }\n ]\n },\n \"research\": {\n \"skipResearch\": false\n }\n }\n }\n ],\n \"applicant\": {\n \"firstName\": \"John\",\n \"lastName\": \"Smith\",\n \"ssn\": \"123-45-6789\",\n \"birthday\": \"1990-05-15\",\n \"phone\": \"+1-555-123-4567\",\n \"email\": \"john.smith@example.com\",\n \"signedReleaseFileUrl\": \"https://example.com/signed-release.pdf\",\n \"addresses\": [\n {\n \"addressType\": \"home\",\n \"addressLine1\": \"456 Oak Avenue\",\n \"addressLine2\": null,\n \"addressCity\": \"Los Angeles\",\n \"addressState\": \"CA\",\n \"addressZipCode\": \"90210\",\n \"addressCountry\": \"US\",\n \"startDate\": \"2021-01-01\",\n \"endDate\": null\n },\n {\n \"addressType\": \"home\",\n \"addressLine1\": \"123 Main Street\",\n \"addressLine2\": \"Apt 4B\",\n \"addressCity\": \"New York\",\n \"addressState\": \"NY\",\n \"addressZipCode\": \"10001\",\n \"addressCountry\": \"US\",\n \"startDate\": \"2020-01-01\",\n \"endDate\": \"2021-01-01\"\n }\n ],\n \"applicantAlias\": [\n {\n \"firstName\": \"Jonathan\",\n \"lastName\": \"Smith\",\n \"middleName\": \"Michael\",\n \"suffix\": \"Jr.\"\n }\n ]\n },\n \"businessContext\": {\n \"entityName\": \"Acme Corp\",\n \"appliedJobTitle\": \"Senior Software Engineer\",\n \"worksiteCity\": \"San Francisco\",\n \"worksiteState\": \"CA\",\n \"proposedSalary\": 100000,\n \"positionLevel\": \"STANDARD\",\n \"securityClearanceRequired\": false,\n \"industrySector\": \"TECHNOLOGY\"\n },\n \"history\": {\n \"employment\": [\n {\n \"employerName\": \"Tech Corp\",\n \"position\": \"Software Engineer\",\n \"employerLocation\": \"San Francisco, CA\",\n \"employerEmail\": \"hr@techcorp.com\",\n \"employerPhone\": \"+1-555-123-4567\",\n \"startDate\": \"2020-01-15\",\n \"endDate\": \"2023-06-30\"\n }\n ]\n }\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Authorization", "Bearer <token>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://sandbox.theary.ai/background-check/v1/orders")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"searchTypes\": [\n {\n \"searchType\": \"EMPLOYMENT\",\n \"externalSearchId\": \"12345678\",\n \"questionnaireUrl\": \"https://verify.example.com/form/abc123\",\n \"questionnaireAccessCode\": \"ACCESS123\",\n \"searchConfig\": {\n \"channels\": {\n \"email\": true,\n \"voice\": false,\n \"preferredChannel\": \"EMAIL\",\n \"blockedDestinations\": [\n \"hr-noreply@company.com\"\n ]\n },\n \"timing\": {\n \"searchSlaMinutes\": 2880,\n \"outboundWindowMinutes\": 120,\n \"businessHours\": {\n \"timezone\": \"America/Chicago\",\n \"startTime\": \"09:00\",\n \"endTime\": \"16:00\",\n \"allowedDays\": [\n 1,\n 2,\n 3,\n 4,\n 5\n ]\n }\n },\n \"outbound\": {\n \"maxAttemptsPerMethod\": 5,\n \"maxTotalAttempts\": 12,\n \"cancelOutboundOnTerminalInbound\": true,\n \"contactHints\": [\n {\n \"email\": \"hr@company.com\",\n \"priority\": \"HIGH\"\n }\n ]\n },\n \"research\": {\n \"skipResearch\": false\n }\n }\n }\n ],\n \"applicant\": {\n \"firstName\": \"John\",\n \"lastName\": \"Smith\",\n \"ssn\": \"123-45-6789\",\n \"birthday\": \"1990-05-15\",\n \"phone\": \"+1-555-123-4567\",\n \"email\": \"john.smith@example.com\",\n \"signedReleaseFileUrl\": \"https://example.com/signed-release.pdf\",\n \"addresses\": [\n {\n \"addressType\": \"home\",\n \"addressLine1\": \"456 Oak Avenue\",\n \"addressLine2\": null,\n \"addressCity\": \"Los Angeles\",\n \"addressState\": \"CA\",\n \"addressZipCode\": \"90210\",\n \"addressCountry\": \"US\",\n \"startDate\": \"2021-01-01\",\n \"endDate\": null\n },\n {\n \"addressType\": \"home\",\n \"addressLine1\": \"123 Main Street\",\n \"addressLine2\": \"Apt 4B\",\n \"addressCity\": \"New York\",\n \"addressState\": \"NY\",\n \"addressZipCode\": \"10001\",\n \"addressCountry\": \"US\",\n \"startDate\": \"2020-01-01\",\n \"endDate\": \"2021-01-01\"\n }\n ],\n \"applicantAlias\": [\n {\n \"firstName\": \"Jonathan\",\n \"lastName\": \"Smith\",\n \"middleName\": \"Michael\",\n \"suffix\": \"Jr.\"\n }\n ]\n },\n \"businessContext\": {\n \"entityName\": \"Acme Corp\",\n \"appliedJobTitle\": \"Senior Software Engineer\",\n \"worksiteCity\": \"San Francisco\",\n \"worksiteState\": \"CA\",\n \"proposedSalary\": 100000,\n \"positionLevel\": \"STANDARD\",\n \"securityClearanceRequired\": false,\n \"industrySector\": \"TECHNOLOGY\"\n },\n \"history\": {\n \"employment\": [\n {\n \"employerName\": \"Tech Corp\",\n \"position\": \"Software Engineer\",\n \"employerLocation\": \"San Francisco, CA\",\n \"employerEmail\": \"hr@techcorp.com\",\n \"employerPhone\": \"+1-555-123-4567\",\n \"startDate\": \"2020-01-15\",\n \"endDate\": \"2023-06-30\"\n }\n ]\n }\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://sandbox.theary.ai/background-check/v1/orders")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"searchTypes\": [\n {\n \"searchType\": \"EMPLOYMENT\",\n \"externalSearchId\": \"12345678\",\n \"questionnaireUrl\": \"https://verify.example.com/form/abc123\",\n \"questionnaireAccessCode\": \"ACCESS123\",\n \"searchConfig\": {\n \"channels\": {\n \"email\": true,\n \"voice\": false,\n \"preferredChannel\": \"EMAIL\",\n \"blockedDestinations\": [\n \"hr-noreply@company.com\"\n ]\n },\n \"timing\": {\n \"searchSlaMinutes\": 2880,\n \"outboundWindowMinutes\": 120,\n \"businessHours\": {\n \"timezone\": \"America/Chicago\",\n \"startTime\": \"09:00\",\n \"endTime\": \"16:00\",\n \"allowedDays\": [\n 1,\n 2,\n 3,\n 4,\n 5\n ]\n }\n },\n \"outbound\": {\n \"maxAttemptsPerMethod\": 5,\n \"maxTotalAttempts\": 12,\n \"cancelOutboundOnTerminalInbound\": true,\n \"contactHints\": [\n {\n \"email\": \"hr@company.com\",\n \"priority\": \"HIGH\"\n }\n ]\n },\n \"research\": {\n \"skipResearch\": false\n }\n }\n }\n ],\n \"applicant\": {\n \"firstName\": \"John\",\n \"lastName\": \"Smith\",\n \"ssn\": \"123-45-6789\",\n \"birthday\": \"1990-05-15\",\n \"phone\": \"+1-555-123-4567\",\n \"email\": \"john.smith@example.com\",\n \"signedReleaseFileUrl\": \"https://example.com/signed-release.pdf\",\n \"addresses\": [\n {\n \"addressType\": \"home\",\n \"addressLine1\": \"456 Oak Avenue\",\n \"addressLine2\": null,\n \"addressCity\": \"Los Angeles\",\n \"addressState\": \"CA\",\n \"addressZipCode\": \"90210\",\n \"addressCountry\": \"US\",\n \"startDate\": \"2021-01-01\",\n \"endDate\": null\n },\n {\n \"addressType\": \"home\",\n \"addressLine1\": \"123 Main Street\",\n \"addressLine2\": \"Apt 4B\",\n \"addressCity\": \"New York\",\n \"addressState\": \"NY\",\n \"addressZipCode\": \"10001\",\n \"addressCountry\": \"US\",\n \"startDate\": \"2020-01-01\",\n \"endDate\": \"2021-01-01\"\n }\n ],\n \"applicantAlias\": [\n {\n \"firstName\": \"Jonathan\",\n \"lastName\": \"Smith\",\n \"middleName\": \"Michael\",\n \"suffix\": \"Jr.\"\n }\n ]\n },\n \"businessContext\": {\n \"entityName\": \"Acme Corp\",\n \"appliedJobTitle\": \"Senior Software Engineer\",\n \"worksiteCity\": \"San Francisco\",\n \"worksiteState\": \"CA\",\n \"proposedSalary\": 100000,\n \"positionLevel\": \"STANDARD\",\n \"securityClearanceRequired\": false,\n \"industrySector\": \"TECHNOLOGY\"\n },\n \"history\": {\n \"employment\": [\n {\n \"employerName\": \"Tech Corp\",\n \"position\": \"Software Engineer\",\n \"employerLocation\": \"San Francisco, CA\",\n \"employerEmail\": \"hr@techcorp.com\",\n \"employerPhone\": \"+1-555-123-4567\",\n \"startDate\": \"2020-01-15\",\n \"endDate\": \"2023-06-30\"\n }\n ]\n }\n}"
response = http.request(request)
puts response.read_body{
"verificationOrderId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"searchIds": [
"3c90c3cc-0d44-4b50-8888-8dd25736052a"
]
}{
"statusCode": 400,
"message": "Validation failed",
"error": "Bad Request"
}{
"statusCode": 400,
"message": "Validation failed",
"error": "Bad Request"
}Orders API
Create Order
Create a background check order
POST
/
background-check
/
v1
/
orders
Create single verification order
curl --request POST \
--url https://sandbox.theary.ai/background-check/v1/orders \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"searchTypes": [
{
"searchType": "EMPLOYMENT",
"externalSearchId": "12345678",
"questionnaireUrl": "https://verify.example.com/form/abc123",
"questionnaireAccessCode": "ACCESS123",
"searchConfig": {
"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
}
}
}
],
"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
},
{
"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": {
"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",
"startDate": "2020-01-15",
"endDate": "2023-06-30"
}
]
}
}
'import requests
url = "https://sandbox.theary.ai/background-check/v1/orders"
payload = {
"searchTypes": [
{
"searchType": "EMPLOYMENT",
"externalSearchId": "12345678",
"questionnaireUrl": "https://verify.example.com/form/abc123",
"questionnaireAccessCode": "ACCESS123",
"searchConfig": {
"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 }
}
}
],
"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": None,
"addressCity": "Los Angeles",
"addressState": "CA",
"addressZipCode": "90210",
"addressCountry": "US",
"startDate": "2021-01-01",
"endDate": None
},
{
"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": {
"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",
"startDate": "2020-01-15",
"endDate": "2023-06-30"
}
] }
}
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({
searchTypes: [
{
searchType: 'EMPLOYMENT',
externalSearchId: '12345678',
questionnaireUrl: 'https://verify.example.com/form/abc123',
questionnaireAccessCode: 'ACCESS123',
searchConfig: {
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}
}
}
],
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
},
{
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: {
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',
startDate: '2020-01-15',
endDate: '2023-06-30'
}
]
}
})
};
fetch('https://sandbox.theary.ai/background-check/v1/orders', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://sandbox.theary.ai/background-check/v1/orders",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'searchTypes' => [
[
'searchType' => 'EMPLOYMENT',
'externalSearchId' => '12345678',
'questionnaireUrl' => 'https://verify.example.com/form/abc123',
'questionnaireAccessCode' => 'ACCESS123',
'searchConfig' => [
'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
]
]
]
],
'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
],
[
'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' => [
'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',
'startDate' => '2020-01-15',
'endDate' => '2023-06-30'
]
]
]
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"Content-Type: application/json"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://sandbox.theary.ai/background-check/v1/orders"
payload := strings.NewReader("{\n \"searchTypes\": [\n {\n \"searchType\": \"EMPLOYMENT\",\n \"externalSearchId\": \"12345678\",\n \"questionnaireUrl\": \"https://verify.example.com/form/abc123\",\n \"questionnaireAccessCode\": \"ACCESS123\",\n \"searchConfig\": {\n \"channels\": {\n \"email\": true,\n \"voice\": false,\n \"preferredChannel\": \"EMAIL\",\n \"blockedDestinations\": [\n \"hr-noreply@company.com\"\n ]\n },\n \"timing\": {\n \"searchSlaMinutes\": 2880,\n \"outboundWindowMinutes\": 120,\n \"businessHours\": {\n \"timezone\": \"America/Chicago\",\n \"startTime\": \"09:00\",\n \"endTime\": \"16:00\",\n \"allowedDays\": [\n 1,\n 2,\n 3,\n 4,\n 5\n ]\n }\n },\n \"outbound\": {\n \"maxAttemptsPerMethod\": 5,\n \"maxTotalAttempts\": 12,\n \"cancelOutboundOnTerminalInbound\": true,\n \"contactHints\": [\n {\n \"email\": \"hr@company.com\",\n \"priority\": \"HIGH\"\n }\n ]\n },\n \"research\": {\n \"skipResearch\": false\n }\n }\n }\n ],\n \"applicant\": {\n \"firstName\": \"John\",\n \"lastName\": \"Smith\",\n \"ssn\": \"123-45-6789\",\n \"birthday\": \"1990-05-15\",\n \"phone\": \"+1-555-123-4567\",\n \"email\": \"john.smith@example.com\",\n \"signedReleaseFileUrl\": \"https://example.com/signed-release.pdf\",\n \"addresses\": [\n {\n \"addressType\": \"home\",\n \"addressLine1\": \"456 Oak Avenue\",\n \"addressLine2\": null,\n \"addressCity\": \"Los Angeles\",\n \"addressState\": \"CA\",\n \"addressZipCode\": \"90210\",\n \"addressCountry\": \"US\",\n \"startDate\": \"2021-01-01\",\n \"endDate\": null\n },\n {\n \"addressType\": \"home\",\n \"addressLine1\": \"123 Main Street\",\n \"addressLine2\": \"Apt 4B\",\n \"addressCity\": \"New York\",\n \"addressState\": \"NY\",\n \"addressZipCode\": \"10001\",\n \"addressCountry\": \"US\",\n \"startDate\": \"2020-01-01\",\n \"endDate\": \"2021-01-01\"\n }\n ],\n \"applicantAlias\": [\n {\n \"firstName\": \"Jonathan\",\n \"lastName\": \"Smith\",\n \"middleName\": \"Michael\",\n \"suffix\": \"Jr.\"\n }\n ]\n },\n \"businessContext\": {\n \"entityName\": \"Acme Corp\",\n \"appliedJobTitle\": \"Senior Software Engineer\",\n \"worksiteCity\": \"San Francisco\",\n \"worksiteState\": \"CA\",\n \"proposedSalary\": 100000,\n \"positionLevel\": \"STANDARD\",\n \"securityClearanceRequired\": false,\n \"industrySector\": \"TECHNOLOGY\"\n },\n \"history\": {\n \"employment\": [\n {\n \"employerName\": \"Tech Corp\",\n \"position\": \"Software Engineer\",\n \"employerLocation\": \"San Francisco, CA\",\n \"employerEmail\": \"hr@techcorp.com\",\n \"employerPhone\": \"+1-555-123-4567\",\n \"startDate\": \"2020-01-15\",\n \"endDate\": \"2023-06-30\"\n }\n ]\n }\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Authorization", "Bearer <token>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://sandbox.theary.ai/background-check/v1/orders")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"searchTypes\": [\n {\n \"searchType\": \"EMPLOYMENT\",\n \"externalSearchId\": \"12345678\",\n \"questionnaireUrl\": \"https://verify.example.com/form/abc123\",\n \"questionnaireAccessCode\": \"ACCESS123\",\n \"searchConfig\": {\n \"channels\": {\n \"email\": true,\n \"voice\": false,\n \"preferredChannel\": \"EMAIL\",\n \"blockedDestinations\": [\n \"hr-noreply@company.com\"\n ]\n },\n \"timing\": {\n \"searchSlaMinutes\": 2880,\n \"outboundWindowMinutes\": 120,\n \"businessHours\": {\n \"timezone\": \"America/Chicago\",\n \"startTime\": \"09:00\",\n \"endTime\": \"16:00\",\n \"allowedDays\": [\n 1,\n 2,\n 3,\n 4,\n 5\n ]\n }\n },\n \"outbound\": {\n \"maxAttemptsPerMethod\": 5,\n \"maxTotalAttempts\": 12,\n \"cancelOutboundOnTerminalInbound\": true,\n \"contactHints\": [\n {\n \"email\": \"hr@company.com\",\n \"priority\": \"HIGH\"\n }\n ]\n },\n \"research\": {\n \"skipResearch\": false\n }\n }\n }\n ],\n \"applicant\": {\n \"firstName\": \"John\",\n \"lastName\": \"Smith\",\n \"ssn\": \"123-45-6789\",\n \"birthday\": \"1990-05-15\",\n \"phone\": \"+1-555-123-4567\",\n \"email\": \"john.smith@example.com\",\n \"signedReleaseFileUrl\": \"https://example.com/signed-release.pdf\",\n \"addresses\": [\n {\n \"addressType\": \"home\",\n \"addressLine1\": \"456 Oak Avenue\",\n \"addressLine2\": null,\n \"addressCity\": \"Los Angeles\",\n \"addressState\": \"CA\",\n \"addressZipCode\": \"90210\",\n \"addressCountry\": \"US\",\n \"startDate\": \"2021-01-01\",\n \"endDate\": null\n },\n {\n \"addressType\": \"home\",\n \"addressLine1\": \"123 Main Street\",\n \"addressLine2\": \"Apt 4B\",\n \"addressCity\": \"New York\",\n \"addressState\": \"NY\",\n \"addressZipCode\": \"10001\",\n \"addressCountry\": \"US\",\n \"startDate\": \"2020-01-01\",\n \"endDate\": \"2021-01-01\"\n }\n ],\n \"applicantAlias\": [\n {\n \"firstName\": \"Jonathan\",\n \"lastName\": \"Smith\",\n \"middleName\": \"Michael\",\n \"suffix\": \"Jr.\"\n }\n ]\n },\n \"businessContext\": {\n \"entityName\": \"Acme Corp\",\n \"appliedJobTitle\": \"Senior Software Engineer\",\n \"worksiteCity\": \"San Francisco\",\n \"worksiteState\": \"CA\",\n \"proposedSalary\": 100000,\n \"positionLevel\": \"STANDARD\",\n \"securityClearanceRequired\": false,\n \"industrySector\": \"TECHNOLOGY\"\n },\n \"history\": {\n \"employment\": [\n {\n \"employerName\": \"Tech Corp\",\n \"position\": \"Software Engineer\",\n \"employerLocation\": \"San Francisco, CA\",\n \"employerEmail\": \"hr@techcorp.com\",\n \"employerPhone\": \"+1-555-123-4567\",\n \"startDate\": \"2020-01-15\",\n \"endDate\": \"2023-06-30\"\n }\n ]\n }\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://sandbox.theary.ai/background-check/v1/orders")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"searchTypes\": [\n {\n \"searchType\": \"EMPLOYMENT\",\n \"externalSearchId\": \"12345678\",\n \"questionnaireUrl\": \"https://verify.example.com/form/abc123\",\n \"questionnaireAccessCode\": \"ACCESS123\",\n \"searchConfig\": {\n \"channels\": {\n \"email\": true,\n \"voice\": false,\n \"preferredChannel\": \"EMAIL\",\n \"blockedDestinations\": [\n \"hr-noreply@company.com\"\n ]\n },\n \"timing\": {\n \"searchSlaMinutes\": 2880,\n \"outboundWindowMinutes\": 120,\n \"businessHours\": {\n \"timezone\": \"America/Chicago\",\n \"startTime\": \"09:00\",\n \"endTime\": \"16:00\",\n \"allowedDays\": [\n 1,\n 2,\n 3,\n 4,\n 5\n ]\n }\n },\n \"outbound\": {\n \"maxAttemptsPerMethod\": 5,\n \"maxTotalAttempts\": 12,\n \"cancelOutboundOnTerminalInbound\": true,\n \"contactHints\": [\n {\n \"email\": \"hr@company.com\",\n \"priority\": \"HIGH\"\n }\n ]\n },\n \"research\": {\n \"skipResearch\": false\n }\n }\n }\n ],\n \"applicant\": {\n \"firstName\": \"John\",\n \"lastName\": \"Smith\",\n \"ssn\": \"123-45-6789\",\n \"birthday\": \"1990-05-15\",\n \"phone\": \"+1-555-123-4567\",\n \"email\": \"john.smith@example.com\",\n \"signedReleaseFileUrl\": \"https://example.com/signed-release.pdf\",\n \"addresses\": [\n {\n \"addressType\": \"home\",\n \"addressLine1\": \"456 Oak Avenue\",\n \"addressLine2\": null,\n \"addressCity\": \"Los Angeles\",\n \"addressState\": \"CA\",\n \"addressZipCode\": \"90210\",\n \"addressCountry\": \"US\",\n \"startDate\": \"2021-01-01\",\n \"endDate\": null\n },\n {\n \"addressType\": \"home\",\n \"addressLine1\": \"123 Main Street\",\n \"addressLine2\": \"Apt 4B\",\n \"addressCity\": \"New York\",\n \"addressState\": \"NY\",\n \"addressZipCode\": \"10001\",\n \"addressCountry\": \"US\",\n \"startDate\": \"2020-01-01\",\n \"endDate\": \"2021-01-01\"\n }\n ],\n \"applicantAlias\": [\n {\n \"firstName\": \"Jonathan\",\n \"lastName\": \"Smith\",\n \"middleName\": \"Michael\",\n \"suffix\": \"Jr.\"\n }\n ]\n },\n \"businessContext\": {\n \"entityName\": \"Acme Corp\",\n \"appliedJobTitle\": \"Senior Software Engineer\",\n \"worksiteCity\": \"San Francisco\",\n \"worksiteState\": \"CA\",\n \"proposedSalary\": 100000,\n \"positionLevel\": \"STANDARD\",\n \"securityClearanceRequired\": false,\n \"industrySector\": \"TECHNOLOGY\"\n },\n \"history\": {\n \"employment\": [\n {\n \"employerName\": \"Tech Corp\",\n \"position\": \"Software Engineer\",\n \"employerLocation\": \"San Francisco, CA\",\n \"employerEmail\": \"hr@techcorp.com\",\n \"employerPhone\": \"+1-555-123-4567\",\n \"startDate\": \"2020-01-15\",\n \"endDate\": \"2023-06-30\"\n }\n ]\n }\n}"
response = http.request(request)
puts response.read_body{
"verificationOrderId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"searchIds": [
"3c90c3cc-0d44-4b50-8888-8dd25736052a"
]
}{
"statusCode": 400,
"message": "Validation failed",
"error": "Bad Request"
}{
"statusCode": 400,
"message": "Validation failed",
"error": "Bad Request"
}Create Order
Creates one background check order. Use sandbox to validate request shape and move the same contract to production with production credentials. SupportedsearchType 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 verification questions for this search (max 50). 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
UsedefaultSearchConfig 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.addressesis optional. Employment and education verification usebusinessContext.worksite*and history locations, not home address.- If
addressesis non-empty: exactly one current address (endDate: nullor omitted);startDatemust be beforeendDateon 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
ReplaceYOUR_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
UsedefaultSearchConfig 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" }
]
}
}
}
]
}
Example response
{
"verificationOrderId": "123e4567-e89b-12d3-a456-426614174000",
"searchIds": ["456e7890-e89b-12d3-a456-426614174001"]
}
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"
}
Authorizations
Bearer authentication header of the form Bearer <token>, where <token> is your auth token.
Body
application/json
Person being verified. Include identity, optional contact details, optional address history, and optional aliases.
Show child attributes
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."
}
]
}
Hiring context for the role the applicant is applying for (employer, title, worksite, salary). This is not the applicant home address.
Show child attributes
Show child attributes
Example:
{
"entityName": "Acme Corp",
"appliedJobTitle": "Senior Software Engineer",
"worksiteCity": "San Francisco",
"worksiteState": "CA",
"proposedSalary": 100000,
"positionLevel": "STANDARD",
"securityClearanceRequired": false,
"industrySector": "TECHNOLOGY"
}
Searches to run on this order. Only EMPLOYMENT and EDUCATION are supported. At least one search is recommended.
Show child attributes
Show child attributes
Example:
[
{
"searchType": "EMPLOYMENT",
"externalSearchId": "12345678",
"questionnaireUrl": "https://verify.example.com/form/abc123",
"questionnaireAccessCode": "ACCESS123",
"searchConfig": {
"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 }
}
}
]
Employment and/or education records to verify for this order.
Show child attributes
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"
}
]
}
Optional per-order webhook routing and signing. Takes precedence over organization-level webhook configuration.
Show child attributes
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"]
}
]
}
Order-level default search policy applied to every created search that does not set searchTypes[i].searchConfig. When a per-search searchConfig is present (even as {}), it fully replaces this default for that search.
Show child attributes
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 }
}
⌘I