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

EnvironmentBase URL
Sandboxhttps://sandbox.theary.com
Productionhttps://api.theary.ai
All paths below are relative to your chosen base URL (for example, POST https://sandbox.theary.com/background-check/v1/orders).

​
Quick start checklist

  • Contact SNH AI for sandbox access (you receive a Bearer JWT with tenant claim). Authentication.
  • Verify connectivity: GET https://sandbox.theary.com/health (no auth).
  • Test auth: GET https://sandbox.theary.com/background-check/v1/orders with Authorization.
  • Create a test order with the JSON body in Create order or Quickstart.
  • Poll GET …/orders/{id}/searches or handle webhooks for progress and completion.
  • Validate X-Webhook-Signature before processing webhook events.
  • When satisfied, contact SNH AI for production credentials (https://api.theary.ai).

​
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: 
Authorization: Bearer <your-jwt>
Your token must include the tenant SNH AI configures for your account. See Authentication.
  1. Obtain a JWT and verify connectivity with GET /health (see Quickstart).
  2. Optionally attach a signed release PDF in applicant.signedReleaseFileUrl — HTTPS URL, gs:// URI from Generate upload URL, or inline base64 (max 10MB). See Signed release file.
  3. Create an order with POST /background-check/v1/orders using VerificationRequest (requires applicant, businessContext, searchTypes; add history, webhookConfig, defaultSearchConfig as needed).
  4. Track work with webhooks first (Webhook overview); poll Get order, List searches, or Get search as a supplement.
  5. Handle errors with retries for transient failures (Error handling).
For copy-paste variations (employment-only, education-only, third-party vendor bans, channel policy, batch caveats), see Integration patterns.

​
Stable consumer endpoints

AreaMethod & pathPurpose
HealthGET /healthLiveness (response shape may vary by deployment).
OrdersPOST /background-check/v1/ordersCreate one order (returns verificationOrderId, searchIds).
OrdersGET /background-check/v1/ordersPaginated list of orders.
OrdersGET /background-check/v1/orders/{id}Order with related data.
OrdersDELETE /background-check/v1/orders/{id}Cancel order and associated searches (best-effort).
SearchesGET /background-check/v1/orders/{id}/searchesAll searches for an order.
SearchesGET /background-check/v1/orders/{id}/searches/{searchId}One search including activity when present.
FilesGET /files/release-form/generate-upload-urlPresigned upload + fileUri for release PDFs.
InboundPOST /background-check/v1/inbound/notificationsSubmit inbound verification payloads (contact-submitted material).
BatchesPOST /background-check/v1/batchesSubmit many orders in one request (see limitations below).

​
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 tenant 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.

​
Endpoints with limited or placeholder behavior

Treat the following as not suitable for production batch orchestration until behavior is expanded:
  • GET /background-check/v1/batches — Returns an empty batches list and a message that batch tracking is not implemented.
  • GET /background-check/v1/batches/{id} — Placeholder; no persisted batch entity.
  • DELETE /background-check/v1/batches/{id} — Placeholder; does not delete orders. Cancel orders with DELETE /background-check/v1/orders/{id}.
  • GET /background-check/v1/orders/{id}/events — Stub; returns an empty events array. Prefer webhooks and search activity from Get search.
POST /background-check/v1/batches runs createOrder for each entry in Promise.all: 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. There is no durable batch id tied to storage today (response batchId is synthetic).

​
OpenAPI note

The repo’s generated openapi.json may list internal or non-nav routes (research, Microsoft Graph hooks, voice, etc.). This Mintlify site’s sidebar is curated for external consumers; if a route is not documented 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 (often Nest-style statusCode, message, error). See Error handling.

​
Next steps

Quickstart

Token, health, optional upload, create order, poll searches

Sandbox reference

Sandbox limits before production

Order lifecycle

Create, inspect, complete

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