Get order searches

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

import requests

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

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/orders/{id}/searches', 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/orders/{id}/searches",
  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/orders/{id}/searches"

	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/orders/{id}/searches")
  .header("Authorization", "Bearer <token>")
  .asString();

require 'uri'
require 'net/http'

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

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

[
  {
    "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "orderId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "applicantId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "externalSearchId": "<string>",
    "displayName": "<string>",
    "displayValue": "<string>",
    "metadata": {},
    "completedAt": "2023-11-07T05:31:56Z",
    "createdAt": "2023-11-07T05:31:56Z",
    "updatedAt": "2023-11-07T05:31:56Z"
  }
]

{
  "statusCode": 400,
  "message": "Validation failed",
  "error": "Bad Request"
}

GET

background-check

orders

{id}

searches

Get order searches

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

import requests

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

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/orders/{id}/searches', 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/orders/{id}/searches",
  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/orders/{id}/searches"

	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/orders/{id}/searches")
  .header("Authorization", "Bearer <token>")
  .asString();

require 'uri'
require 'net/http'

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

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

[
  {
    "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "orderId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "applicantId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "externalSearchId": "<string>",
    "displayName": "<string>",
    "displayValue": "<string>",
    "metadata": {},
    "completedAt": "2023-11-07T05:31:56Z",
    "createdAt": "2023-11-07T05:31:56Z",
    "updatedAt": "2023-11-07T05:31:56Z"
  }
]

{
  "statusCode": 400,
  "message": "Validation failed",
  "error": "Bad Request"
}

Get Order Searches

Use this endpoint to read search progress and verification results for every search on an order. Prefer webhooks for production completion; use this call when you need to poll or reconcile state. This is different from Get order, which returns an order overview and only a summary of related searches (no verificationResult). This endpoint returns the full search list with outcomes. For outreach and inbound activity on a single search, use Get specific search.

Path Parameters

string

required

Unique identifier of the verification order (UUID format)

Response

Returns a raw array of search objects (not wrapped in { orders: ... } or similar). Each search includes status, metadata, applicant (scalar fields), and verificationResult (empty while in progress; typically one entry when complete). Unlike Get order, this response does not include order-level fields such as orderStatus or proposedPosition.

array

Array of search objects

Show Search Object Properties

string

Unique search identifier (UUID).

string

Parent order identifier (UUID).

string

Applicant identifier (UUID).

string

External system search identifier (as submitted; may be null).

string

Type of search: EMPLOYMENT or EDUCATION.

string

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

string

Human-readable label for the search (e.g. the entity being verified). May be null.

string

Secondary display value for the search. May be null.

object

Search-type-specific details captured at creation — e.g. claimed employer/institution, location, dates, salary, and derived fields. Shape varies by searchType. Defaults to {}.

string

Additional comments or notes for the search. May be null.

string

Online questionnaire URL, if provided at creation. May be null.

string

Access code for the online questionnaire, if provided. May be null.

string

Resolved signed release file URI stored on the search (gs:// or HTTPS). May be null.

string

Search completion timestamp, or null while in progress.

string

Search creation timestamp (ISO 8601).

string

Last update timestamp (ISO 8601).

object

Applicant scalar fields (same shape as the order applicant).

array

Verification results for this search (0 or 1 entry — one result per search).

Show VerificationResult Properties

string

Result identifier (UUID).

string

Owning search identifier (UUID).

string

Terminal outcome, e.g. VERIFIED, NO_RECORD, ACTION_REQUIRED.

string

Human-readable summary of findings.

object

Structured extracted verification data. May be null.

boolean

Whether a discrepancy was detected. May be null.

string

When the inbound result was submitted. May be null.

string

Creation timestamp.

string

Last update timestamp.

isRedacted (on applicant) indicates the applicant’s PII (SSN, address, and similar fields) has been redacted from the record. See Data handling and privacy for details.

Example Request

curl -sS -X GET "https://sandbox.theary.ai/background-check/v1/orders/550e8400-e29b-41d4-a716-446655440000/searches" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Accept: application/json"

const orderId = '550e8400-e29b-41d4-a716-446655440000'
const response = await fetch(`/background-check/v1/orders/${orderId}/searches`, {
  method: 'GET',
  headers: {
    Authorization: 'Bearer YOUR_JWT_TOKEN',
    'Content-Type': 'application/json',
  },
})

const searches = await response.json()

import requests

order_id = "550e8400-e29b-41d4-a716-446655440000"
headers = {
    'Authorization': 'Bearer YOUR_JWT_TOKEN',
    'Content-Type': 'application/json'
}

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

searches = response.json()

Example Response

[
  {
    "id": "6ba7b810-9dad-11d1-80b4-00c04fd430c8",
    "orderId": "550e8400-e29b-41d4-a716-446655440000",
    "applicantId": "789e4567-e89b-12d3-a456-426614174002",
    "externalSearchId": "client-emp-001",
    "searchType": "EMPLOYMENT",
    "searchStatus": "IN_PROGRESS",
    "displayName": "Acme Corp",
    "displayValue": "Senior Software Engineer",
    "metadata": {
      "employerName": "Acme Corp",
      "employerLocation": "Cupertino, CA",
      "startDate": "2020-01-15",
      "endDate": "2023-06-30"
    },
    "additionalComments": "Verify salary and job responsibilities",
    "questionnaireUrl": "https://verify.example.com/form/abc123",
    "questionnaireAccessCode": "ACCESS123",
    "signedReleaseFileUrl": "gs://verification-api-storage/tenants/acme/releaseForms/uuid.pdf",
    "completedAt": null,
    "createdAt": "2026-01-15T10:30:00Z",
    "updatedAt": "2026-01-15T10:30:00Z",
    "applicant": {
      "id": "789e4567-e89b-12d3-a456-426614174002",
      "firstName": "John",
      "lastName": "Smith",
      "ssn": "123-45-6789",
      "birthday": "1990-05-15",
      "phone": "+1-555-123-4567",
      "email": "john.smith@example.com",
      "isRedacted": false,
      "createdAt": "2026-01-15T10:30:00Z",
      "updatedAt": "2026-01-15T10:30:00Z"
    },
    "verificationResult": []
  },
  {
    "id": "6ba7b811-9dad-11d1-80b4-00c04fd430c8",
    "orderId": "550e8400-e29b-41d4-a716-446655440000",
    "applicantId": "789e4567-e89b-12d3-a456-426614174002",
    "externalSearchId": "client-edu-001",
    "searchType": "EDUCATION",
    "searchStatus": "COMPLETED",
    "displayName": "Stanford University",
    "displayValue": "Bachelor of Computer Science",
    "metadata": {
      "institutionName": "Stanford University",
      "institutionLocation": "Stanford, CA",
      "graduationDate": "2020-06-15"
    },
    "additionalComments": null,
    "questionnaireUrl": null,
    "questionnaireAccessCode": null,
    "signedReleaseFileUrl": null,
    "completedAt": "2026-01-14T15:45:00Z",
    "createdAt": "2026-01-15T10:30:00Z",
    "updatedAt": "2026-01-14T15:45:00Z",
    "applicant": {
      "id": "789e4567-e89b-12d3-a456-426614174002",
      "firstName": "John",
      "lastName": "Smith",
      "ssn": "123-45-6789",
      "birthday": "1990-05-15",
      "phone": "+1-555-123-4567",
      "email": "john.smith@example.com",
      "isRedacted": false,
      "createdAt": "2026-01-15T10:30:00Z",
      "updatedAt": "2026-01-15T10:30:00Z"
    },
    "verificationResult": [
      {
        "id": "123e4567-e89b-12d3-a456-426614174004",
        "searchId": "6ba7b811-9dad-11d1-80b4-00c04fd430c8",
        "outcome": "VERIFIED",
        "resultDetails": "Degree verified successfully",
        "fullVerification": { "degree": "BS Computer Science", "graduationDate": "2020-06-15" },
        "discrepancy": false,
        "submittedAt": "2026-01-14T16:00:00Z",
        "createdAt": "2026-01-14T16:00:00Z",
        "updatedAt": "2026-01-14T16:00:00Z"
      }
    ]
  }
]

When to use this vs Get order

Goal	Endpoint
Overall order status and applicant summary	Get order
Poll search status and pull `verificationResult` for all searches	This endpoint
Activity log (outbound/inbound) for one search	Get specific search

Use Cases

Poll for verification outcomes when webhooks are unavailable or as a reconciliation fallback
Display per-search status and results in your UI after create
Confirm searchStatus / outcome after a verification.completed webhook
Export search-level results for reporting without loading activity history

Authorizations

Authorization

string

header

required

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

Path Parameters

string<uuid>

required

Response

Array of search objects for the order

string<uuid>

orderId

string<uuid>

applicantId

string<uuid>

externalSearchId

string | null

searchType

enum<string>

Available options:

EMPLOYMENT,

EDUCATION

searchStatus

enum<string>

Current search status

Available options:

IN_PROGRESS,

COMPLETED,

CANCELLED,

REASSIGNED

displayName

string | null

displayValue

string | null

metadata

object

completedAt

string<date-time> | null

createdAt

string<date-time>

updatedAt

string<date-time>

Delete Order Get Specific Search

Overview

Orders API

Search Management

Batches API

Inbound API

Files API

Closeout Events API

Request and order schemas

Webhook schemas

Get Order Searches

Get Order Searches

Path Parameters

Response

Example Request

Example Response

When to use this vs Get order

Use Cases

Authorizations

Path Parameters

Response

​Get Order Searches

​Path Parameters

​Response

​Example Request

​Example Response

​When to use this vs Get order

​Use Cases

Authorizations

Path Parameters

Response

Get Order Searches

Path Parameters

Response

Example Request

Example Response

When to use this vs Get order

Use Cases