Error
A valid request URL is required to generate request examples{}Orders API
Get Specific Search
Retrieve one search with verification results and activity history
GET
/
background-check
/
v1
/
orders
/
{id}
/
searches
/
{searchId}
Error
A valid request URL is required to generate request examples{}Get Specific Search
Use this endpoint for a single search in detail: the same search fields andverificationResult 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
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
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
searchIdafter listing searches - Reconcile state after a webhook when you need activity context