Skip to main content

​
Quickstart

Use sandbox to validate your integration, then move the same request shapes to production credentials and https://api.theary.ai.

​
1. Configure environment

export API_BASE_URL="https://sandbox.theary.com"
export AUTH_TOKEN="<your-jwt>"
Your JWT must include the tenant claim configured for your account. See Authentication.

​
2. Verify connectivity

curl "$API_BASE_URL/health"

​
3. Create an employment order

See Create order — field reference for all required and optional fields. Applicant home address (applicant.addresses) is optional.

​
Minimal order (no home address)

{
  "searchTypes": [{ "searchType": "EMPLOYMENT", "externalSearchId": "client-emp-001" }],
  "applicant": {
    "firstName": "John",
    "lastName": "Smith",
    "ssn": "123-45-6789"
  },
  "businessContext": {
    "entityName": "Apple",
    "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)

Copy this JSON body as-is to the Create order page, or save it as order.json and send it with cURL. 
{
  "searchTypes": [
    {
      "searchType": "EMPLOYMENT",
      "externalSearchId": "client-emp-001"
    }
  ],
  "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
      }
    ]
  },
  "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",
        "employerLocation": "San Francisco, CA",
        "employerEmail": "hr@techcorp.com",
        "employerPhone": "+1-555-123-4567",
        "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"
  }
}

curl -X POST "$API_BASE_URL/background-check/v1/orders" \
  -H "Authorization: Bearer $AUTH_TOKEN" \
  -H "Content-Type: application/json" \
  --data @order.json
The response includes verificationOrderId and searchIds.

​
4. Track progress

curl "$API_BASE_URL/background-check/v1/orders/{verificationOrderId}/searches" \
  -H "Authorization: Bearer $AUTH_TOKEN"
Use webhooks for production completion events, and use polling as a fallback. See Webhook integration.

​
Optional: attach a signed release

If you want a signed release PDF attached to outbound verification requests, set applicant.signedReleaseFileUrl using one of these options:
OptionWhen to use
HTTPS URLYou host the PDF at a stable public URL
GCS uploadRecommended for larger files — upload to SNH AI storage first
Inline base64Small PDFs (max 10MB) when you want a single request without a separate upload step
  1. Call Generate upload URL.
  2. PUT the PDF to the returned signedUrl with Content-Type: application/pdf.
  3. Put the returned fileUri in applicant.signedReleaseFileUrl.

​
Inline base64

Send the PDF as raw base64 or a data:application/pdf;base64,... data URL in applicant.signedReleaseFileUrl. The API uploads it to cloud storage at order creation and stores a gs:// URI on each search. See Applicant schema — Signed release file for validation rules and examples.

​
Optional: ban a third-party vendor

If a client does not want a search routed to a specific third-party vendor, add thirdPartyBan inside searchConfig. 
{
  "searchTypes": [
    {
      "searchType": "EMPLOYMENT",
      "externalSearchId": "client-emp-001",
      "searchConfig": {
        "thirdPartyBan": ["TALX_WORK_NUMBER"]
      }
    }
  ]
}
For multiple vendors, deferral behavior, and the full supported vendor-code list, see Third-party ban.

​
Next steps