Skip to main content

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.

​
Integration patterns

Each snippet focuses on the differing parts of a Create order request. Combine with full field requirements from Applicant, Business context, History, and VerificationRequest.

​
Employment-only

{
  "applicant": { "...": "..." },
  "businessContext": {
    "entityName": "Acme Corp",
    "appliedJobTitle": "Engineer",
    "worksiteCity": "Austin",
    "worksiteState": "TX",
    "proposedSalary": 120000
  },
  "searchTypes": [{ "searchType": "EMPLOYMENT" }],
  "history": {
    "employment": [
      {
        "employerName": "Acme Corp",
        "position": "Engineer",
        "startDate": "2020-01-01",
        "endDate": "2023-06-30"
      }
    ]
  }
}

​
Education-only

{
  "applicant": { "...": "..." },
  "businessContext": {
    "entityName": "State University",
    "appliedJobTitle": "Research Assistant",
    "proposedSalary": 0
  },
  "searchTypes": [{ "searchType": "EDUCATION" }],
  "history": {
    "education": [
      {
        "institutionName": "State University",
        "qualification": "BS Computer Science",
        "fieldOfStudy": "CS",
        "graduationDate": "2018-05-15",
        "institutionContactEmail": "registrar@example.edu"
      }
    ]
  }
}

​
Employment and education on one order

{
  "searchTypes": [{ "searchType": "EMPLOYMENT" }, { "searchType": "EDUCATION" }],
  "history": {
    "employment": [{ "...": "..." }],
    "education": [{ "...": "..." }]
  }
}
(Include complete applicant and businessContext as for a single-type order.)

​
Known contacts / skip broad research

Use defaultSearchConfig or per-search searchConfig with research.skipResearch: true and seed outbound.contactHints. See Search config. 
{
  "defaultSearchConfig": {
    "research": { "skipResearch": true },
    "outbound": {
      "contactHints": [{ "email": "hr@employer.com", "priority": "HIGH" }]
    }
  }
}

​
Email-only outreach

{
  "defaultSearchConfig": {
    "channels": {
      "email": true,
      "voice": false,
      "fax": false,
      "preferredChannel": "EMAIL"
    }
  }
}

​
Manual review (inbound)

{
  "searchTypes": [
    {
      "searchType": "EMPLOYMENT",
      "searchConfig": { "inbound": { "requireManualReview": true } }
    }
  ]
}

​
Per-search webhook routing

Use WebhookTarget objects under closeoutEndpoints and fallbackEndpoint (string URL, single object, or array). Example: send employment closeouts to one URL and everything else to a fallback: 
{
  "webhookConfig": {
    "enabled": true,
    "secret": "shared-or-per-target-secret",
    "closeoutEndpoints": {
      "EMPLOYMENT": [
        {
          "url": "https://client.example/webhooks/employment",
          "events": ["verification.completed", "verification.notification"]
        }
      ]
    },
    "fallbackEndpoint": [
      {
        "url": "https://client.example/webhooks/other",
        "events": ["verification.action_required", "verification.notification"],
        "searchTypes": ["EDUCATION"]
      }
    ]
  }
}

​
Release-form upload

  1. GET /files/release-form/generate-upload-url → signedUrl, fileUri
  2. PUT PDF to signedUrl
  3. Set applicant.signedReleaseFileUrl to fileUri (gs://...)
Generate upload URL

​
Batch create caveats

POST /background-check/v1/batches accepts { "orders": [ ...VerificationRequestDto ] } and creates each order in parallel via the same path as single-order creation. The response includes a synthetic batchId and per-order verificationOrderId / searchIds in orders. Validation / creation errors: if any order fails validation or throws during createOrder, the whole HTTP request fails with an error (you do not get a 200 with mixed success/failure). Partial success risk: if the server fails after some orders were created (timeout, connection drop), you can be left with some orders already persisted. Persist every returned verificationOrderId as soon as you receive the response and reconcile with List orders. Not implemented: listing batches, fetching a batch by id, and deleting a batch return placeholder payloads; track orders with List orders, Get order, and Get order searches.

​
Webhook idempotency

Deliveries may retry. Deduplicate with the X-Event-Id header (unique per delivery) and your own externalSearchId when you set it on searches. Acknowledge with a 2xx response; see Webhook events and Webhook integration.