> ## 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. # Background Check API Overview > Consumer map: environments, stable endpoints, async lifecycle, and webhooks. # Background Check API Overview The Background Check API creates **verification orders**, runs **employment** and **education** searches asynchronously, and notifies your systems via **webhooks**. Every request is scoped by the **`tenant`** claim in your JWT. ## Base URLs | Environment | Base URL | | ----------- | --------------------------- | | Sandbox | `https://sandbox.theary.ai` | | Production | `https://api.theary.ai` | All paths below are relative to your chosen base URL (for example, `POST https://sandbox.theary.ai/background-check/v1/orders`). For a first successful call, follow the [Quickstart](/quickstart). Authentication details: [Authentication](/getting-started/authentication). ## Authentication Send a Bearer JWT on every request **except** unauthenticated health (if your deployment exposes `GET /health` without auth—confirm with your environment). Typical pattern: ```http theme={null} Authorization: Bearer ``` Your token must include the **`tenant`** claim SNH AI configures for your organization. See [Authentication](/getting-started/authentication). ## Stable consumer endpoints | Area | Method & path | Purpose | | -------- | ----------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ | | Health | `GET /health` | Liveness (response shape may vary by deployment). | | Orders | `POST /background-check/v1/orders` | Create one order (returns `verificationOrderId`, `searchIds`). | | Orders | `GET /background-check/v1/orders` | Paginated list of orders. | | Orders | `GET /background-check/v1/orders/{id}` | Order overview: `orderStatus`, applicant, **summary** of searches (no results). | | Orders | `DELETE /background-check/v1/orders/{id}` | Cancel order and associated searches (best-effort). | | Searches | `GET /background-check/v1/orders/{id}/searches` | All searches with status and `verificationResult` — poll for outcomes. | | Searches | `GET /background-check/v1/orders/{id}/searches/{searchId}` | One search with results **and** `activity` history. | | Searches | [`PATCH /background-check/v1/orders/{id}/searches/{searchId}`](/api-reference/endpoints/update-search) | Update the status or resolution of an existing search. | | Searches | [`GET /background-check/v1/orders/{orderId}/searches/{searchId}/contacts`](/api-reference/endpoints/manage-search-contacts) | Get contacts for an existing search contact plan. | | Searches | [`POST /background-check/v1/orders/{orderId}/searches/{searchId}/contact`](/api-reference/endpoints/manage-search-contacts) | Add a contact to an existing search contact plan. | | Searches | [`PUT /background-check/v1/orders/{orderId}/searches/{searchId}/contact`](/api-reference/endpoints/manage-search-contacts) | Update an existing search contact. | | Searches | [`POST /background-check/v1/orders/{orderId}/searches/{searchId}/contact/mark-accuracy`](/api-reference/endpoints/manage-search-contacts) | Mark a search contact accurate or inaccurate with a reason. | | Searches | [`DELETE /background-check/v1/orders/{orderId}/searches/{searchId}/contact`](/api-reference/endpoints/manage-search-contacts) | Remove a contact from an existing search contact plan. | | Searches | [`GET /background-check/v1/orders/{orderId}/searches/{searchId}/outbounds`](/api-reference/endpoints/manage-outbounds) | List actionable outbounds for a search, including status and IDs. | | Searches | [`POST /background-check/v1/orders/{orderId}/searches/{searchId}/cancel-outbounds`](/api-reference/endpoints/manage-outbounds) | Permanently cancel pending outbounds for a search. | | Searches | [`POST /background-check/v1/orders/{orderId}/searches/{searchId}/pause-outbounds`](/api-reference/endpoints/manage-outbounds) | Pause all pending outbounds for a search. | | Searches | [`POST /background-check/v1/orders/{orderId}/searches/{searchId}/resume-outbounds`](/api-reference/endpoints/manage-outbounds) | Resume all paused outbounds for a search. | | Searches | [`POST /background-check/v1/orders/{orderId}/searches/{searchId}/pause-outbound`](/api-reference/endpoints/manage-outbounds) | Pause one outbound by `outboundId`. | | Searches | [`POST /background-check/v1/orders/{orderId}/searches/{searchId}/resume-outbound`](/api-reference/endpoints/manage-outbounds) | Resume one paused outbound by `outboundId`. | | Searches | [`GET /background-check/v1/searches/by-external-id/{externalSearchId}`](/api-reference/endpoints/get-search-by-external-id) | Integrator lookup by your `externalSearchId`; returns `{ exists, externalSearchId, searches[] }`. Use for idempotency/dedupe before creating an order. | | Files | `GET /files/release-form/generate-upload-url` | Presigned upload + `fileUri` for release PDFs. | | Inbound | `POST /background-check/v1/inbound/notifications` | Submit inbound verification payloads (contact-submitted material). | | Batches | `POST /background-check/v1/batches` | Submit many orders in one request (see below for details). | | Closeout | [`GET /v1/closeout-events`](/api-reference/endpoints/closeout-events) | Poll/query closeout event history across searches. Note the shorter `/v1/` prefix — see [API versioning](#api-versioning) below. | ## Search types Configure `searchTypes` on each order. Supported values: **`EMPLOYMENT`** and **`EDUCATION`** only. See [SearchType](/api-reference/schemas/search-type) and the [Create order field reference](/api-reference/endpoints/create-order#request-body-field-reference). Use [Search config](/api-reference/schemas/search-config) at order level (`defaultSearchConfig`) or per search (`searchTypes[i].searchConfig`) for research, outbound, channel, inbound, notification, and third-party vendor-ban overrides. ## Async lifecycle and webhooks Orders and searches move through backend workflow phases **asynchronously**. Do not assume a search is finished when the create-order response returns. Configure `webhookConfig` on the order (or rely on organization defaults) so you receive: * `verification.completed` — terminal verification outcome. * `verification.action_required` — manual follow-up or escalation. * `verification.notification` — progress-style updates when enabled for your routing. Use [WebhookTarget](/api-reference/schemas/webhook-target) shapes for `closeoutEndpoints` and `fallbackEndpoint` (string URL, single object, or array). Verify **HMAC-SHA256** signatures using your shared secret. Details: [Webhook overview](/webhooks/overview), [Events](/webhooks/events), [Integration](/webhooks/integration). ## Batch and event endpoints Batch **create** (`POST /batches`) is supported for multi-order submission. There is no batch list/get/delete surface — track work through individual orders, searches, and webhooks: * Track order-level status with [List orders](/api-reference/endpoints/list-orders) and [Get order](/api-reference/endpoints/get-order). * Poll search status and verification results with [Get order searches](/api-reference/endpoints/get-order-searches). * Cancel with **`DELETE /background-check/v1/orders/{id}`**. * For live outcomes, prefer [webhooks](/webhooks/overview). For outreach history on one search, use [Get specific search](/api-reference/endpoints/get-specific-search). **`POST /background-check/v1/batches`** creates each order in the request in parallel: if one order fails validation, the whole request fails; if the server fails mid-flight, some orders may already exist—**record returned `verificationOrderId` values per order** and reconcile. Use those IDs (and order endpoints) for tracking; the response `batchId` is a request correlation id. ## Request correlation and observability Every API response includes a unique request identifier that you can use for debugging and support escalations: | Header | Description | | -------------- | -------------------------------------------------------------------------------------------------------- | | `X-Request-Id` | Unique identifier for the API request. Include this value when contacting support about a specific call. | Webhook deliveries include `X-Event-Id` for deduplication and correlation. See [Webhook headers](/webhooks/integration#webhook-headers). When troubleshooting, correlate your requests using: 1. **`X-Request-Id`** on API responses for tracing a specific HTTP call 2. **`verificationOrderId`** and **`searchId`** for tracking the lifecycle of orders and searches 3. **`externalSearchId`** for mapping back to your internal systems 4. **`X-Event-Id`** on webhook deliveries for deduplicating retried events Include these identifiers in support tickets to accelerate resolution. ## API versioning and stability All documented background-check endpoints are versioned under `/background-check/v1/`. The `v1` API is stable: * Breaking changes require a new major version with advance notice * Additive changes (new optional fields, new enum values) may be introduced to maintain compatibility with expanding platform capabilities * Existing required fields and status codes remain unchanged within a version For forward compatibility, integrations should accept and ignore unrecognized fields in responses and webhook payloads. ### Deprecation policy When a breaking change is necessary, SNH AI follows this process: 1. **Announcement**: Breaking changes are communicated at least 90 days before the cutover date via email to registered integration contacts 2. **Dual support**: Both the old and new API versions are available during the migration window 3. **Sunset**: The old version is decommissioned after the migration window closes Subscribe to the [status page](https://status.theary.ai) for platform announcements. ## OpenAPI note The published `openapi.json` covers the public consumer surface documented in this site. If a route is not listed here, assume it is not a supported public integration surface unless SNH AI enables it for you. ## Errors The API uses conventional HTTP status codes and JSON bodies with a standard error shape (`statusCode`, `message`, `error`). See [Errors](/api-reference/errors). ## Next steps Token, health, create order, track searches Sandbox limits before production Orders, searches, and webhooks Suppress routing to specific third-party vendors Full request reference Events, routing, and signatures Request and webhook field reference Sandbox JWT and tenant claims