Skip to main content

​
Background Check API Overview

The Background Check API is an agentic service that autonomously conducts employment and education verification for background screening.

​
Base URL

https://api.theary.ai

​
Quick Start Example

Create your first verification order: 
curl -X POST "https://api.theary.ai/background-check/v1/orders" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "applicant": {
      "firstName": "John",
      "lastName": "Doe",
      "email": "john.doe@example.com"
    },
    "searchTypes": [{
      "searchType": "EMPLOYMENT"
    }],
    "businessContext": {
      "entityName": "Tech Corp",
      "appliedJobTitle": "Software Engineer"
    }
  }'

​
Core Endpoints

CategoryDescriptionExample Endpoint
HealthService health and status checksGET /health
OrdersCreate and manage background check ordersPOST /background-check/v1/orders
Order DetailsGet specific order informationGET /background-check/v1/orders/:id
List OrdersRetrieve paginated list of ordersGET /background-check/v1/orders
SearchesGet searches for a specific orderGET /background-check/v1/orders/:id/searches
EventsGet activity events for an orderGET /background-check/v1/orders/:id/events
BatchesProcess multiple orders in batchesPOST /background-check/v1/batches
InboundSubmit verification responsesPOST /background-check/v1/inbound/notifications

​
Authentication

All endpoints (except /health) require JWT Bearer token authentication: 
Authorization: Bearer YOUR_JWT_TOKEN
Learn more about authentication.

​
Verification Types

The API supports these verification types:
  • Employment - Verify work history, job titles, dates
  • Education - Verify degrees, graduation dates, institutions
Learn more about search types.

​
Webhooks

Receive real-time notifications when verifications complete: 
{
  "webhookConfig": {
    "enabled": true,
    "fallbackEndpoint": "https://your-app.com/webhooks/verifications",
    "secret": "your-webhook-secret"
  }
}
Learn more about webhooks.

​
Getting Started

​
1. Authentication

Obtain your API credentials from your THEARY account and include the JWT token in all requests.

​
2. Create an Order

Submit a verification order with applicant details and search types: 
POST /background-check/v1/orders
See Create Order for full documentation.

​
3. Monitor Progress

Track order status and retrieve results: 
GET /background-check/v1/orders/:id
See Get Order for details.

​
4. Receive Notifications

Configure webhooks to get notified when verifications complete, or submit responses from employers/schools via the inbound endpoint. See Submit Inbound Notification for submitting verification responses.

​
Error Handling

The API uses standard HTTP status codes:
  • 200 - Success
  • 400 - Bad Request
  • 401 - Unauthorized
  • 404 - Not Found
  • 422 - Validation Error
  • 500 - Server Error
Learn more about error handling.

​
Rate Limits

Standard API rate limits apply. Contact support if you need higher limits.

​
Next Steps

Create Your First Order

Submit a verification order with the Orders API

Webhooks

Receive real-time verification notifications

Authentication Guide

Learn how to authenticate API requests

Search Types

Understand different verification types