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

​
Create Batch Orders

Submits an array of verification requests. The server runs createOrder for each entry in parallel (Promise.all) and returns a synthetic 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

​
orders
array
required
Non-empty array of objects with the same shape as Create order (applicant, businessContext, searchTypes, optional history, webhookConfig, defaultSearchConfig, etc.).

​
Response

​
success
boolean
true when all orders in the batch were created without error
​
batchId
string
Client-facing id generated for this request (not stored server-side for later GET list/batch)
​
ordersCreated
number
Count of orders returned in orders
​
orders
array
Array of per-order results from createOrder (same shapes as single create)

​
Example Request

Each element in orders must match VerificationRequest. Minimal employment-oriented example (two orders): 
curl -X POST "https://sandbox.theary.com/background-check/v1/batches" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: 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": "Apple",
          "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": "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