Skip to main content

​
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

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. Authentication details: 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:
Your token must include the tenant claim SNH AI configures for your organization. See Authentication.

​
Stable consumer endpoints

​
Search types

Configure searchTypes on each order. Supported values: EMPLOYMENT and EDUCATION only. See SearchType and the Create order field reference. Use 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 shapes for closeoutEndpoints and fallbackEndpoint (string URL, single object, or array). Verify HMAC-SHA256 signatures using your shared secret. Details: Webhook overview, Events, 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: 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: Webhook deliveries include X-Event-Id for deduplication and correlation. See 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 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.

​
Next steps

Quickstart

Token, health, create order, track searches

Environments

Sandbox limits before production

Core concepts

Orders, searches, and webhooks

Third-party ban

Suppress routing to specific third-party vendors

Create order

Full request reference

Webhooks

Events, routing, and signatures

Schemas

Request and webhook field reference

Authentication

Sandbox JWT and tenant claims