Get specific search within order

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

import requests

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

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/{searchId}', 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/{searchId}",
  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/{searchId}"

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

require 'uri'
require 'net/http'

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

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",
  "verificationResult": [
    {
      "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "searchId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "resultDetails": "<string>",
      "fullVerification": {},
      "discrepancy": true,
      "submittedAt": "2023-11-07T05:31:56Z",
      "createdAt": "2023-11-07T05:31:56Z",
      "updatedAt": "2023-11-07T05:31:56Z"
    }
  ],
  "activity": [
    {
      "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "searchId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "applicantId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "contactId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "channelValue": "<string>",
      "description": "<string>",
      "metadata": {},
      "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

{searchId}

Get specific search within order

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

import requests

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

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/{searchId}', 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/{searchId}",
  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/{searchId}"

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

require 'uri'
require 'net/http'

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

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",
  "verificationResult": [
    {
      "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "searchId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "resultDetails": "<string>",
      "fullVerification": {},
      "discrepancy": true,
      "submittedAt": "2023-11-07T05:31:56Z",
      "createdAt": "2023-11-07T05:31:56Z",
      "updatedAt": "2023-11-07T05:31:56Z"
    }
  ],
  "activity": [
    {
      "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "searchId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "applicantId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "contactId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "channelValue": "<string>",
      "description": "<string>",
      "metadata": {},
      "createdAt": "2023-11-07T05:31:56Z",
      "updatedAt": "2023-11-07T05:31:56Z"
    }
  ]
}

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

Get Specific Search

Use this endpoint for a single search in detail: the same search fields and verificationResult as Get order searches, plus the activity array (outbound and inbound communications). Use Get order for order-level status only. Use Get order searches when you need results for every search on the order without activity logs.

Path Parameters

string

required

Unique identifier of the verification order (UUID format)

string

required

Unique identifier of the specific search (UUID format)

Response

string

Unique search identifier (UUID format)

string

Parent order identifier (UUID format)

string

Applicant identifier

string

External system search identifier

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 (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

URL to online verification questionnaire (if applicable). May be null.

string

Access code for online questionnaire. May be null.

string

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

string

Search completion timestamp

string

Search creation timestamp

string

Last update timestamp

object

Complete applicant information

isRedacted (on applicant) — when true, PII fields have been cleared per your organization’s data retention terms.

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.

array

Array of activity records for this search.

Show Activity Properties

string

Activity identifier (UUID).

string

Owning search identifier (UUID).

string

Applicant identifier (UUID).

string

Associated contact identifier (UUID), or null.

string

Type: INBOUND or OUTBOUND.

string

Communication channel: EMAIL, FAX, VOICE, or JSON.

string

Contact destination (email address, fax/phone number).

string

Activity description. May be null.

object

Channel-specific activity metadata. Defaults to {}.

string

Activity timestamp (ISO 8601).

string

Last update timestamp (ISO 8601).

Example Request

curl -sS -X GET "https://sandbox.theary.ai/background-check/v1/orders/550e8400-e29b-41d4-a716-446655440000/searches/6ba7b810-9dad-11d1-80b4-00c04fd430c8" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Accept: application/json"

const orderId = '550e8400-e29b-41d4-a716-446655440000'
const searchId = '6ba7b810-9dad-11d1-80b4-00c04fd430c8'
const response = await fetch(`/background-check/v1/orders/${orderId}/searches/${searchId}`, {
  method: 'GET',
  headers: {
    Authorization: 'Bearer YOUR_JWT_TOKEN',
    'Content-Type': 'application/json',
  },
})

const search = await response.json()

import requests

order_id = "550e8400-e29b-41d4-a716-446655440000"
search_id = "6ba7b810-9dad-11d1-80b4-00c04fd430c8"
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/{search_id}',
    headers=headers
)

search = response.json()

Example Response

{
  "id": "6ba7b810-9dad-11d1-80b4-00c04fd430c8",
  "orderId": "550e8400-e29b-41d4-a716-446655440000",
  "applicantId": "6ba7b812-9dad-11d1-80b4-00c04fd430c8",
  "externalSearchId": "client-emp-001",
  "searchType": "EMPLOYMENT",
  "searchStatus": "COMPLETED",
  "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": "2026-01-16T14:30:00Z",
  "createdAt": "2026-01-15T10:30:00Z",
  "updatedAt": "2026-01-16T14: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": "123e4567-e89b-12d3-a456-426614174004",
      "searchId": "6ba7b810-9dad-11d1-80b4-00c04fd430c8",
      "outcome": "VERIFIED",
      "resultDetails": "Employment verified: John Smith worked as Senior Software Engineer at Acme Corp from 2020-01-15 to 2023-06-30. Salary confirmed.",
      "fullVerification": { "position": "Senior Software Engineer", "salaryConfirmed": true },
      "discrepancy": false,
      "submittedAt": "2026-01-16T15:00:00Z",
      "createdAt": "2026-01-16T15:00:00Z",
      "updatedAt": "2026-01-16T15:00:00Z"
    }
  ],
  "activity": [
    {
      "id": "activity_789e4567-e89b-12d3-a456-426614174005",
      "searchId": "6ba7b810-9dad-11d1-80b4-00c04fd430c8",
      "applicantId": "6ba7b812-9dad-11d1-80b4-00c04fd430c8",
      "contactId": "contact_1a2b3c4d-5e6f-7a8b-9c0d-1e2f3a4b5c6d",
      "activityType": "OUTBOUND",
      "channel": "EMAIL",
      "channelValue": "hr@acme.example",
      "description": "Employment verification request sent",
      "metadata": {},
      "createdAt": "2026-01-15T11:00:00Z",
      "updatedAt": "2026-01-15T11:00:00Z"
    },
    {
      "id": "activity_012e4567-e89b-12d3-a456-426614174006",
      "searchId": "6ba7b810-9dad-11d1-80b4-00c04fd430c8",
      "applicantId": "6ba7b812-9dad-11d1-80b4-00c04fd430c8",
      "contactId": "contact_1a2b3c4d-5e6f-7a8b-9c0d-1e2f3a4b5c6d",
      "activityType": "INBOUND",
      "channel": "EMAIL",
      "channelValue": "hr@acme.example",
      "description": "Employment verification response received",
      "metadata": {},
      "createdAt": "2026-01-16T14:15:00Z",
      "updatedAt": "2026-01-16T14:15:00Z"
    }
  ]
}

Search not found

{
  "error": "Search not found",
  "orderId": "550e8400-e29b-41d4-a716-446655440000",
  "searchId": "6ba7b810-9dad-11d1-80b4-00c04fd430c8"
}

When to use this vs other read endpoints

Goal	Endpoint
Order status / applicant overview	Get order
Results for all searches on the order	Get order searches
One search plus outreach/inbound activity	This endpoint

Use Cases

Audit who was contacted and which channel was used (activity)
Troubleshoot a stuck search with outbound/inbound history
Load a detail view for one searchId after listing searches
Reconcile state after a webhook when you need activity context

Authorizations

Authorization

string

header

required

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

Path Parameters

string<uuid>

required

searchId

string<uuid>

required

Response

Search details with verification results and activity (or error body if not found — check for the error field)

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>

verificationResult

object[]

Show child attributes

activity

object[]

Show child attributes

Get Order Searches Update Order Search

Overview

Orders API

Search Management

Batches API

Inbound API

Files API

Closeout Events API

Request and order schemas

Webhook schemas

Get Specific Search

Get Specific Search

Path Parameters

Response

Example Request

Example Response

Search not found

When to use this vs other read endpoints

Use Cases

Authorizations

Path Parameters

Response

​Get Specific Search

​Path Parameters

​Response

​Example Request

​Example Response

​Search not found

​When to use this vs other read endpoints

​Use Cases

Authorizations

Path Parameters

Response

Get Specific Search

Path Parameters

Response

Example Request

Example Response

Search not found

When to use this vs other read endpoints

Use Cases