Skip to main content
POST
https://api.theary.ai
/
background-check
/
v1
/
batches
Create Batch Order
curl --request POST \
  --url https://api.theary.ai/background-check/v1/batches \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "orders": [
    {}
  ]
}
'
{
  "success": true,
  "batchId": "<string>",
  "ordersCreated": 123,
  "orders": [
    {
      "verificationOrderId": "<string>",
      "searchIds": [
        {}
      ]
    }
  ]
}

​
Create Batch Orders

Creates multiple verification orders simultaneously in a single batch operation for efficient bulk processing.

​
Request

​
orders
array
required
Array of verification order requests (minimum 1 order required). Each order object has the same structure as the individual order creation endpoint, including optional webhook configuration.

​
Response

​
success
boolean
Whether the batch was created successfully
​
batchId
string
Unique identifier for the batch operation
​
ordersCreated
number
Number of orders successfully created
​
orders
array
Array of created order results

​
Example Request

curl -X POST "https://api.theary.ai/background-check/v1/batches" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "orders": [
      {
        "searchTypes": [
          {
            "searchType": "EMPLOYMENT",
            "searchTitle": "Software Engineer"
          }
        ],
        "applicant": {
          "firstName": "John",
          "lastName": "Smith",
          "ssn": "123-45-6789",
          "email": "[email protected]"
        },
        "entityName": "Apple",
        "jobTitle": "Senior Software Developer",
        "employmentDates": {
          "startDate": "2020-01-15"
        },
        "proposedSalary": 100000,
        "entityLocation": "San Francisco, CA",
        "webhookConfig": {
          "enabled": true,
          "secret": "webhook-secret-for-hmac-validation",
          "retryAttempts": 3,
          "closeoutEndpoints": {
            "EMPLOYMENT": "https://client.example.com/webhooks/employment-closeout"
          },
          "fallbackEndpoint": "https://client.example.com/webhooks/search-closeout"
        }
      },
      {
        "searchTypes": [
          {
            "searchType": "EMPLOYMENT", 
            "searchTitle": "Product Manager"
          }
        ],
        "applicant": {
          "firstName": "Jane",
          "lastName": "Doe",
          "ssn": "987-65-4321",
          "email": "[email protected]"
        },
        "entityName": "Google",
        "jobTitle": "Product Manager",
        "employmentDates": {
          "startDate": "2019-03-01"
        },
        "proposedSalary": 120000,
        "entityLocation": "Mountain View, CA"
      }
    ]
  }'

​
Example Response

{
  "success": true,
  "batchId": "batch_1642789123_abc123def",
  "ordersCreated": 2,
  "orders": [
    {
      "verificationOrderId": "ord_123e4567-e89b-12d3-a456-426614174000",
      "searchIds": ["search_456e7890-e89b-12d3-a456-426614174001"]
    },
    {
      "verificationOrderId": "ord_789e4567-e89b-12d3-a456-426614174002",
      "searchIds": ["search_012e7890-e89b-12d3-a456-426614174003"]
    }
  ]
}

​
Notes

  • All orders in a batch are processed atomically - if any order fails, the entire batch fails
  • Each order follows the same validation rules as individual order creation
  • Batch operations are ideal for bulk onboarding or periodic verification workflows