Skip to main content
POST
https://api.theary.ai
/
background-check
/
v1
/
orders
Create Order
curl --request POST \
  --url https://api.theary.ai/background-check/v1/orders \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "applicant": {},
  "businessContext": {},
  "searchTypes": [
    {}
  ],
  "history": {},
  "criminalCheck": {
    "jurisdictions": [
      {}
    ],
    "worksiteState": "<string>",
    "positionLevel": "<string>",
    "securityClearanceRequired": true,
    "industrySector": "<string>"
  },
  "webhookConfig": {
    "enabled": true,
    "secret": "<string>",
    "retryAttempts": 123,
    "closeoutEndpoints": {
      "EMPLOYMENT": "<string>",
      "EDUCATION": "<string>",
      "CRIMINAL": "<string>"
    },
    "fallbackEndpoint": "<string>"
  }
}
'
{
  "statusCode": 400,
  "message": [
    "Criminal check jurisdictions are required when requesting criminal background checks"
  ],
  "error": "Bad Request"
}

​
Create Background Check Order

Creates a new background check order for employment, education, or criminal verification.

​
Request

​
applicant
object
required
Complete applicant information for background check See ApplicantDto for detailed structure.
​
businessContext
object
required
Business context for the new job position the applicant is applying for See BusinessContextDto for detailed structure.
​
searchTypes
array
required
Array of search types to perform See SearchTypeDto for detailed structure.
​
history
object
Historical data for verification including employment and education records (optional) See HistoryDto for detailed structure.
​
criminalCheck
object
Criminal check configuration (required when searchTypes includes CRIMINAL)
​
webhookConfig
object
Optional webhook configuration for this verification request. Takes precedence over tenant-level webhook configuration.

​
Response

​
verificationOrderId
string
Unique identifier for the created verification order
​
searchIds
array
Array of search IDs created for this order

​
Example Request

curl -X POST "https://api.theary.ai/background-check/v1/orders" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "searchTypes": [
      {
        "searchType": "EMPLOYMENT"
      },
      {
        "searchType": "EDUCATION"
      }
    ],
    "applicant": {
      "firstName": "John",
      "lastName": "Smith",
      "ssn": "123-45-6789",
      "birthday": "1990-05-15",
      "phone": "+1-555-123-4567",
      "email": "[email protected]",
      "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": "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",
          "employerEmail": "[email protected]",
          "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": "[email protected]",
          "institutionContactPhone": "+1-510-642-6000"
        }
      ]
    },
    "webhookConfig": {
      "enabled": true,
      "secret": "webhook-secret-for-hmac-validation",
      "retryAttempts": 3,
      "closeoutEndpoints": {
        "EMPLOYMENT": "https://client.example.com/webhooks/employment-closeout",
        "EDUCATION": "https://client.example.com/webhooks/education-closeout"
      },
      "fallbackEndpoint": "https://client.example.com/webhooks/search-closeout"
    }
  }'

​
Example Response

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

​
Error Responses

{
  "statusCode": 400,
  "message": [
    "Criminal check jurisdictions are required when requesting criminal background checks"
  ],
  "error": "Bad Request"
}

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