Error
A valid request URL is required to generate request examples{}Batches API
Create Batch Order
Create multiple verification orders in one request (not a persisted batch)
POST
/
background-check
/
v1
/
batches
Error
A valid request URL is required to generate request examples{}Create Batch Orders
Batch create submits multiple orders in one request. Each order is independent — persist every returned
verificationOrderId and track work with individual order endpoints.batchId plus per-order results.
This is not an atomic transaction: if the request fails after some orders succeed, you may have partial creates. Persist each returned
verificationOrderId / searchIds and reconcile. If any order throws during validation or creation, the whole request fails.Request
array
required
Non-empty array of objects with the same shape as Create order (
applicant, businessContext, searchTypes, optional history, webhookConfig, defaultSearchConfig, etc.).Response
boolean
true when all orders in the batch were created without errorstring
Client-facing id generated for this request (not stored server-side for later GET list/batch)
number
Count of orders returned in
ordersarray
Array of per-order results (same shapes as single create)
Example Request
Each element inorders must match Verification request. Minimal employment-oriented example (two orders):
curl -sS -X POST "https://sandbox.theary.ai/background-check/v1/batches" \
-H "Authorization: Bearer YOUR_JWT_TOKEN" \
-H "Content-Type: application/json" \
-H "Accept: application/json" \
-d '{
"orders": [
{
"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
}
]
},
"businessContext": {
"entityName": "Acme Corp",
"appliedJobTitle": "Senior Software Engineer",
"worksiteCity": "San Francisco",
"worksiteState": "CA",
"proposedSalary": 100000,
"positionLevel": "STANDARD",
"securityClearanceRequired": false,
"industrySector": "TECHNOLOGY"
},
"searchTypes": [{ "searchType": "EMPLOYMENT" }],
"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"
}
]
}
},
{
"applicant": {
"firstName": "Jane",
"lastName": "Doe",
"ssn": "987-65-4321",
"birthday": "1992-08-20",
"phone": "+1-555-987-6543",
"email": "jane.doe@example.com",
"signedReleaseFileUrl": "https://example.com/signed-release-2.pdf",
"addresses": [
{
"addressType": "home",
"addressLine1": "100 Market St",
"addressLine2": null,
"addressCity": "San Francisco",
"addressState": "CA",
"addressZipCode": "94105",
"addressCountry": "US",
"startDate": "2020-06-01",
"endDate": null
}
]
},
"businessContext": {
"entityName": "Acme Corp",
"appliedJobTitle": "Engineer",
"worksiteCity": "Austin",
"worksiteState": "TX",
"proposedSalary": 120000,
"positionLevel": "STANDARD",
"securityClearanceRequired": false,
"industrySector": "TECHNOLOGY"
},
"searchTypes": [{ "searchType": "EMPLOYMENT" }],
"history": {
"employment": [
{
"employerName": "Acme Corp",
"position": "Engineer",
"employerLocation": "Austin, TX",
"startDate": "2019-01-01",
"endDate": "2023-01-01"
}
]
},
"webhookConfig": {
"enabled": true,
"secret": "your-webhook-secret-key",
"retryAttempts": 3,
"closeoutEndpoints": {
"EMPLOYMENT": [
{
"url": "https://your-app.com/webhooks/employment",
"events": ["verification.completed"]
}
]
},
"fallbackEndpoint": [
{
"url": "https://your-app.com/webhooks/all-events",
"events": ["verification.action_required"]
}
]
}
}
]
}'
Example Response
{
"success": true,
"batchId": "batch_1642789123_abc123def",
"ordersCreated": 2,
"orders": [
{
"verificationOrderId": "123e4567-e89b-12d3-a456-426614174000",
"searchIds": ["456e7890-e89b-12d3-a456-426614174001"]
},
{
"verificationOrderId": "789e4567-e89b-12d3-a456-426614174002",
"searchIds": ["012e7890-e89b-12d3-a456-426614174003"]
}
]
}
Error responses
| Status | When |
|---|---|
400 | orders array is empty (at least one order is required). |
400 | Any single order fails validation (same rules as Create order). |
401 | Missing or invalid Bearer JWT, or JWT missing the tenant claim. |
500 | A mid-flight failure while creating orders in parallel. Because orders are created concurrently (see the non-atomic behavior noted above), a failure partway through can surface as a 500 after some orders have already been created — reconcile using the persisted per-order results before retrying. |
{
"statusCode": 400,
"message": ["Batch must contain at least one order"],
"error": "Bad Request"
}
{
"statusCode": 401,
"message": "Unauthorized"
}
Notes
- There is no batch list/get/delete API — track and cancel work with List orders, Get order, and Delete order.
- For webhook shapes see WebhookConfig and WebhookTarget.
Body
application/json
Array of verification orders to process in batch
Show child attributes
Show child attributes
Example:
[{}]
Response
201 - application/json
The response is of type object.