Error
A valid request URL is required to generate request examples{}Orders API
Get Order Searches
List all searches on an order with status and verification results — the polling endpoint for outcomes
GET
/
background-check
/
v1
/
orders
/
{id}
/
searches
Error
A valid request URL is required to generate request examples{}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 (noverificationResult). 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
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
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/outcomeafter averification.completedwebhook - Export search-level results for reporting without loading activity history
Path Parameters
Response
200 - application/json
The response is of type object.