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.ai"
export AUTH_TOKEN="<your-jwt>"

Your JWT must include the tenant claim configured for your account. See Authentication.

2. Verify connectivity

GET /health requires no authentication:

curl -sS -i "$API_BASE_URL/health"

Expected: HTTP 200 with a JSON health payload. Then confirm your token and tenant claim are accepted against an authenticated endpoint:

curl -sS -i "$API_BASE_URL/background-check/v1/orders?page=1&limit=1" \
  -H "Authorization: Bearer $AUTH_TOKEN" \
  -H "Accept: application/json"

A 200 confirms auth is working; a 401 means the token is missing/expired or the tenant claim is invalid (see Authentication).

3. Create an employment order

See Create order — field reference for all required and optional fields. Applicant home address (applicant.addresses) is optional. Set searchTypes[].externalSearchId to your own stable correlation ID. It is echoed back on searches and webhook events and is the key you use to reconcile duplicates — order creation is not idempotent (see Production readiness).

Minimal order (no home address)

{
  "searchTypes": [{ "searchType": "EMPLOYMENT", "externalSearchId": "client-emp-001" }],
  "applicant": {
    "firstName": "John",
    "lastName": "Smith",
    "ssn": "123-45-6789"
  },
  "businessContext": {
    "entityName": "Acme Corp",
    "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. It includes aliases, home address, a questionnaire link, employment history with fax, and per-search webhook routing.

{
  "searchTypes": [
    {
      "searchType": "EMPLOYMENT",
      "externalSearchId": "client-emp-001",
      "questionnaireUrl": "https://verify.example.com/form/abc123",
      "questionnaireAccessCode": "ACCESS123"
    }
  ],
  "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
      }
    ],
    "applicantAlias": [
      {
        "firstName": "Jonathan",
        "lastName": "Smith",
        "middleName": "Michael",
        "suffix": "Jr."
      }
    ]
  },
  "businessContext": {
    "entityName": "Acme Corp",
    "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",
        "employerFax": "+1-555-987-6543",
        "startDate": "2020-01-15",
        "endDate": "2023-06-30"
      }
    ]
  },
  "webhookConfig": {
    "enabled": true,
    "secret": "webhook-secret-for-hmac-validation",
    "retryAttempts": 3,
    "closeoutEndpoints": {
      "EMPLOYMENT": [
        {
          "url": "https://your-app.com/webhooks/employment-closeout",
          "headers": { "X-Customer": "acme" },
          "events": ["verification.completed"]
        }
      ]
    },
    "fallbackEndpoint": "https://your-app.com/webhooks/verification"
  }
}

Field notes for the pieces beyond the minimal body:

searchTypes[].questionnaireUrl / questionnaireAccessCode — direct link and access code for the applicant’s online questionnaire, passed through to outbound verification.
applicant.applicantAlias[] — AKA / former names (firstName and lastName required per entry; middleName, suffix optional). See Applicant alias.
history.employment[].employerFax — fax contact used when policy allows fax outreach.
webhookConfig.closeoutEndpoints — per-search-type routing with optional headers, basicAuth, and events filters; fallbackEndpoint covers anything not matched. See Webhook config.

Education order

Education orders use the same envelope with an EDUCATION search type and history.education records.

{
  "searchTypes": [
    {
      "searchType": "EDUCATION",
      "externalSearchId": "client-edu-001",
      "questionnaireUrl": "https://verify.example.com/form/edu789",
      "questionnaireAccessCode": "EDU789"
    }
  ],
  "applicant": {
    "firstName": "John",
    "lastName": "Smith",
    "ssn": "123-45-6789"
  },
  "businessContext": {
    "entityName": "Acme Corp",
    "appliedJobTitle": "Senior Software Engineer",
    "worksiteCity": "San Francisco",
    "worksiteState": "CA",
    "proposedSalary": 100000
  },
  "history": {
    "education": [
      {
        "institutionName": "University of California",
        "qualification": "Bachelor of Science in Computer Science",
        "fieldOfStudy": "Computer Science",
        "institutionLocation": "Berkeley, CA",
        "startDate": "2014-08-25",
        "endDate": "2018-05-15",
        "graduationDate": "2018-05-15",
        "institutionContactEmail": "registrar@berkeley.edu",
        "institutionContactPhone": "+1-510-642-6000"
      }
    ]
  }
}

Send the request

Save either JSON example above as order.json, then:

curl -sS -X POST "$API_BASE_URL/background-check/v1/orders" \
  -H "Authorization: Bearer $AUTH_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  --data @order.json

Or send the minimal body inline:

curl -sS -X POST "$API_BASE_URL/background-check/v1/orders" \
  -H "Authorization: Bearer $AUTH_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "searchTypes": [{ "searchType": "EMPLOYMENT", "externalSearchId": "client-emp-001" }],
    "applicant": {
      "firstName": "John",
      "lastName": "Smith",
      "ssn": "123-45-6789"
    },
    "businessContext": {
      "entityName": "Acme Corp",
      "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"
        }
      ]
    }
  }'

Example success response:

{
  "verificationOrderId": "123e4567-e89b-12d3-a456-426614174000",
  "searchIds": ["456e7890-e89b-12d3-a456-426614174001"]
}

4. Track progress

Capture the verificationOrderId from the create response, then poll that order’s searches (this example uses jq to extract the ID):

ORDER_ID=$(curl -sS -X POST "$API_BASE_URL/background-check/v1/orders" \
  -H "Authorization: Bearer $AUTH_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  --data @order.json | jq -r '.verificationOrderId')

echo "Created order: $ORDER_ID"

curl -sS "$API_BASE_URL/background-check/v1/orders/$ORDER_ID/searches" \
  -H "Authorization: Bearer $AUTH_TOKEN" \
  -H "Accept: application/json"

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:

Option	When to use
HTTPS URL	You host the PDF at a stable public URL
GCS upload	Recommended for larger files — upload to SNH AI storage first
Inline base64	Small PDFs (max 10MB) when you want a single request without a separate upload step

GCS upload (recommended)

Call Generate upload URL.
PUT the PDF to the returned signedUrl with Content-Type: application/pdf.
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.

Production readiness

Before you leave sandbox, confirm your integration handles these cases:

Duplicate prevention — Always send a stable externalSearchId per search. If a create call fails without a response, look up by externalSearchId before resending to avoid duplicates.
Transient errors and retries — Retry 5xx and network failures with exponential backoff. Do not retry 4xx — fix the request instead. See Errors.
Async timing — A 201 means SNH AI accepted the order, not that verification finished. Turnaround depends on employer responsiveness and channel — typical results arrive within hours, though some verifications take longer. Prefer webhooks for completion and use polling only as a fallback. See Webhook integration.
Webhook security — Always verify the X-Webhook-Signature header with your shared secret before you process an event. See Webhook integration.
SLA and escalation — Searches that cannot finish automatically escalate on organization-configurable timers. See SLA and escalation.
Batching — POST /batches creates each order independently. Record every returned verificationOrderId and track work with individual order endpoints. See Background Check overview.

Next steps

Create order for field-level reference
Get order searches to inspect search state
Third-party ban to suppress specific vendor routing
Webhook integration for production event handling
Environments for sandbox-specific limits

Overview

Platform setup

Quickstart

Quickstart

1. Configure environment

2. Verify connectivity

3. Create an employment order

Minimal order (no home address)

Full example (with home address)

Education order

Send the request

4. Track progress

Optional: attach a signed release

GCS upload (recommended)

Inline base64

Optional: ban a third-party vendor

Production readiness

Next steps

​Quickstart

​1. Configure environment

​2. Verify connectivity

​3. Create an employment order

​Minimal order (no home address)

​Full example (with home address)

​Education order

​Send the request

​4. Track progress

​Optional: attach a signed release

​GCS upload (recommended)

​Inline base64

​Optional: ban a third-party vendor

​Production readiness

​Next steps

Quickstart

1. Configure environment

2. Verify connectivity

3. Create an employment order

Minimal order (no home address)

Full example (with home address)

Education order

Send the request

4. Track progress

Optional: attach a signed release

GCS upload (recommended)

Inline base64

Optional: ban a third-party vendor

Production readiness

Next steps