> ## Documentation Index
> Fetch the complete documentation index at: https://documentation.theary.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Quickstart

> Authenticate, verify connectivity, create an order with JSON, and track searches.

# Quickstart

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

## 1. Configure environment

```bash theme={null}
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](/getting-started/authentication).

## 2. Verify connectivity

`GET /health` requires no authentication:

```bash theme={null}
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:

```bash theme={null}
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](/getting-started/authentication)).

## 3. Create an employment order

See [Create order — field reference](/api-reference/endpoints/create-order#request-body-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](#production-readiness)).

### Minimal order (no home address)

```json theme={null}
{
  "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](/api-reference/endpoints/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.

```json theme={null}
{
  "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](/api-reference/schemas/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](/api-reference/schemas/webhook-config).

### Education order

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

```json theme={null}
{
  "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:

```bash theme={null}
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:

```bash theme={null}
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:

```json theme={null}
{
  "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`](https://jqlang.github.io/jq/) to extract the ID):

```bash theme={null}
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](/webhooks/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)

1. Call [Generate upload URL](/api-reference/endpoints/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](/api-reference/schemas/applicant#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`.

```json theme={null}
{
  "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](/guides/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](/api-reference/errors#retry-logic).
* **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](/webhooks/integration).
* **Webhook security** — Always verify the `X-Webhook-Signature` header with your shared secret before you process an event. See [Webhook integration](/webhooks/integration).
* **SLA and escalation** — Searches that cannot finish automatically escalate on organization-configurable timers. See [SLA and escalation](/guides/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](/api-reference/background-check/overview#batch-and-event-endpoints).

## Next steps

* [Create order](/api-reference/endpoints/create-order) for field-level reference
* [Get order searches](/api-reference/endpoints/get-order-searches) to inspect search state
* [Third-party ban](/guides/third-party-ban) to suppress specific vendor routing
* [Webhook integration](/webhooks/integration) for production event handling
* [Environments](/getting-started/environments) for sandbox-specific limits