Get Search by External ID

Looks up any searches belonging to the authenticated tenant that match the given externalSearchId (the refId you supplied, e.g. from your client system). Upstream integrators use this to avoid recreating or reprocessing a search that already exists for their tenant.

Path Parameters

string

required

External search identifier to look up. Matched exactly as stored — the value is persisted as submitted on create and is not trimmed, so a stored value with leading/trailing spaces will only match an identical lookup value.

Response

boolean

Whether any searches matched the given externalSearchId.

string

Echo of the externalSearchId you looked up.

array

Matching searches for your tenant, ordered by createdAt ascending. Empty array when none match.

Show Search Properties

string

Search identifier (UUID).

string

External search identifier.

string

Type of search: EMPLOYMENT or EDUCATION.

string

Current status: IN_PROGRESS, COMPLETED, CANCELLED, or REASSIGNED.

string

Search creation timestamp (ISO 8601).

A blank or whitespace-only externalSearchId returns { exists: false, externalSearchId, searches: [] } with HTTP 200 rather than an error.

Example Request

curl -sS -X GET "https://sandbox.theary.ai/background-check/v1/searches/by-external-id/client-emp-001" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Accept: application/json"

const externalSearchId = 'client-emp-001'
const response = await fetch(`https://sandbox.theary.ai/background-check/v1/searches/by-external-id/${externalSearchId}`, {
  method: 'GET',
  headers: {
    Authorization: 'Bearer YOUR_JWT_TOKEN',
    'Content-Type': 'application/json',
  },
})

const result = await response.json()

import requests

external_search_id = "client-emp-001"
headers = {
    'Authorization': 'Bearer YOUR_JWT_TOKEN',
    'Content-Type': 'application/json'
}

response = requests.get(
    f'https://sandbox.theary.ai/background-check/v1/searches/by-external-id/{external_search_id}',
    headers=headers
)

result = response.json()

Example Response

{
  "exists": true,
  "externalSearchId": "client-emp-001",
  "searches": [
    {
      "id": "6ba7b810-9dad-11d1-80b4-00c04fd430c8",
      "externalSearchId": "client-emp-001",
      "searchType": "EMPLOYMENT",
      "searchStatus": "COMPLETED",
      "createdAt": "2026-01-15T10:30:00Z"
    }
  ]
}

No match found:

{
  "exists": false,
  "externalSearchId": "client-emp-999",
  "searches": []
}

Error Responses

{
  "statusCode": 401,
  "message": "Unauthorized"
}

Use Cases

Idempotency / dedupe: Check whether a search already exists for your externalSearchId before creating a new order.
Reconciliation: Look up the internal search state for a reference ID from your own system without needing the internal order/search UUIDs.

Overview

Orders API

Search Management

Batches API

Inbound API

Files API

Closeout Events API

Request and order schemas

Webhook schemas

Get Search by External ID

Get Search by External ID

Path Parameters

Response

Example Request

Example Response

Error Responses

Use Cases

​Get Search by External ID

​Path Parameters

​Response

​Example Request

​Example Response

​Error Responses

​Use Cases

Get Search by External ID

Path Parameters

Response

Example Request

Example Response

Error Responses

Use Cases