Look up searches by external search ID

curl --request GET \
  --url https://sandbox.theary.ai/background-check/v1/searches/by-external-id/{externalSearchId} \
  --header 'Authorization: Bearer <token>'

import requests

url = "https://sandbox.theary.ai/background-check/v1/searches/by-external-id/{externalSearchId}"

headers = {"Authorization": "Bearer <token>"}

response = requests.get(url, headers=headers)

print(response.text)

const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

fetch('https://sandbox.theary.ai/background-check/v1/searches/by-external-id/{externalSearchId}', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://sandbox.theary.ai/background-check/v1/searches/by-external-id/{externalSearchId}",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://sandbox.theary.ai/background-check/v1/searches/by-external-id/{externalSearchId}"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("Authorization", "Bearer <token>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.get("https://sandbox.theary.ai/background-check/v1/searches/by-external-id/{externalSearchId}")
  .header("Authorization", "Bearer <token>")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://sandbox.theary.ai/background-check/v1/searches/by-external-id/{externalSearchId}")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Bearer <token>'

response = http.request(request)
puts response.read_body

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

GET

background-check

searches

by-external-id

{externalSearchId}

Look up searches by external search ID

curl --request GET \
  --url https://sandbox.theary.ai/background-check/v1/searches/by-external-id/{externalSearchId} \
  --header 'Authorization: Bearer <token>'

import requests

url = "https://sandbox.theary.ai/background-check/v1/searches/by-external-id/{externalSearchId}"

headers = {"Authorization": "Bearer <token>"}

response = requests.get(url, headers=headers)

print(response.text)

const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

fetch('https://sandbox.theary.ai/background-check/v1/searches/by-external-id/{externalSearchId}', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://sandbox.theary.ai/background-check/v1/searches/by-external-id/{externalSearchId}",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://sandbox.theary.ai/background-check/v1/searches/by-external-id/{externalSearchId}"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("Authorization", "Bearer <token>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.get("https://sandbox.theary.ai/background-check/v1/searches/by-external-id/{externalSearchId}")
  .header("Authorization", "Bearer <token>")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://sandbox.theary.ai/background-check/v1/searches/by-external-id/{externalSearchId}")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Bearer <token>'

response = http.request(request)
puts response.read_body

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

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

externalSearchId

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

exists

boolean

Whether any searches matched the given externalSearchId.

externalSearchId

string

Echo of the externalSearchId you looked up.

searches

array

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

Show Search Properties

string

Search identifier (UUID).

externalSearchId

string

External search identifier.

searchType

string

Type of search: EMPLOYMENT or EDUCATION.

searchStatus

string

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

createdAt

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.

Authorizations

Authorization

string

header

required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Path Parameters

externalSearchId

string

required

External search identifier provided at order creation

Response

200 - application/json

Lookup result

exists

boolean

required

externalSearchId

string

required

searches

object[]

required

Show child attributes

Get Specific Search Cancel Search Activities

Overview

Orders API

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

Authorizations

Path Parameters

Response

​Get Search by External ID

​Path Parameters

​Response

​Example Request

​Example Response

​Error Responses

​Use Cases

Authorizations

Path Parameters

Response

Get Search by External ID

Path Parameters

Response

Example Request

Example Response

Error Responses

Use Cases