Update Order Search

Updates a single search within a verification order. Use this endpoint when you need to close, cancel, or reassign a specific search after the order has been created. The route is order-scoped and validates that searchId belongs to the order identified by id.

Path Parameters

string

required

Verification order UUID.

searchId

string

required

Search UUID within the order.

Request Body

searchStatus

string

required

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

resolution

object

Required when searchStatus is COMPLETED. The outcome field discriminates between a verified closeout and an action-required closeout.

resolution.outcome

string

Terminal outcome. Accepted values:

VERIFIED — verification succeeded.
VERIFIED_DISCREPANCY — verification succeeded with one or more discrepancies.
VERIFIED_NO_DISCREPANCY — verification succeeded without a discrepancy.
ACTION_REQUIRED — the search closed without a verified result and requires downstream action.

The three verified outcomes persist a verification result and emit verification.completed. ACTION_REQUIRED does not persist a verification result and emits verification.action_required.

resolution.reasonCode

string

Required when resolution.outcome is ACTION_REQUIRED and prohibited for verified outcomes.Accepted values:

THIRD_PARTY_RECORD
UPSTREAM_ISSUE
SYSTEM_FAILURE
SLA_REACHED
HUMAN_ESCALATION
PRIMARY_EDUCATION
OTHER

resolution.resultDetails

string | object

Optional result details for verified outcomes. Objects are serialized before persistence.

resolution.submittedAt

string

Optional submission timestamp for verified outcomes.

resolution.metadata

object

Optional additional fields included in the verification.completed result payload for verified outcomes.

reason

string

Human-readable reason for the status update. Included in the SEARCH_UPDATED notification metadata and terminal context where applicable.

metadata

object

Additional metadata included in the SEARCH_UPDATED notification and terminal webhook context where applicable.

For COMPLETED, provide exactly one resolution object. Its outcome determines which terminal operation and webhook the API uses. resolution is prohibited for IN_PROGRESS, REASSIGNED, and CANCELLED.

resolution.reasonCode is required when resolution.outcome is ACTION_REQUIRED and prohibited for verified outcomes.

Status Transitions

Transition	Result
Any terminal status to `IN_PROGRESS`	Rejected with `409`
Any terminal status to a different terminal status	Rejected with `409`
Same status as current	`200` no-op; no webhooks are re-emitted
`IN_PROGRESS` to `COMPLETED` with a verified `resolution.outcome`	Persists the result and emits `verification.notification` (`SEARCH_UPDATED`) and `verification.completed`
`IN_PROGRESS` to `COMPLETED` with `resolution.outcome: ACTION_REQUIRED`	Emits `verification.notification` (`SEARCH_UPDATED`) and `verification.action_required`
`IN_PROGRESS` to `REASSIGNED`	Emits `verification.notification` (`SEARCH_UPDATED`) and `verification.action_required` with `reasonCode: HUMAN_ESCALATION`
`IN_PROGRESS` to `CANCELLED`	Emits `verification.notification` (`SEARCH_UPDATED`) only

Sending the search’s current status returns 200 as a no-op. The API does not re-emit webhooks, cancel outbound work again, or repeat workflow changes.

Terminal Side Effects

Real transitions to COMPLETED, REASSIGNED, or CANCELLED cancel pending and scheduled outbound work for that search and stop workflow processing. Cancellation covers pending outbound work plus SCHEDULED or PAUSED contact attempts.

Already-sent outbound is not recalled.

Order Roll-Up

An order becomes COMPLETED when none of its searches remain IN_PROGRESS. Terminal-for-order search statuses are:

COMPLETED
CANCELLED
REASSIGNED

The parent order is set to COMPLETED when the final in-progress sibling leaves IN_PROGRESS. Use DELETE /background-check/v1/orders/{id} to set an order to CANCELLED.

Example Requests

Complete With a Verification Result

curl -sS -X PATCH "https://sandbox.theary.ai/background-check/v1/orders/550e8400-e29b-41d4-a716-446655440000/searches/7c7b8f66-7f6a-4b52-9e85-8b3f5b7c1111" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "searchStatus": "COMPLETED",
    "resolution": {
      "outcome": "VERIFIED",
      "resultDetails": "Employment dates and title verified by HR.",
      "submittedAt": "2026-07-02T18:00:00.000Z"
    },
    "reason": "Manual verified closeout"
  }'

const orderId = '550e8400-e29b-41d4-a716-446655440000'
const searchId = '7c7b8f66-7f6a-4b52-9e85-8b3f5b7c1111'
const response = await fetch(
  `https://sandbox.theary.ai/background-check/v1/orders/${orderId}/searches/${searchId}`,
  {
    method: 'PATCH',
    headers: {
      Authorization: 'Bearer YOUR_JWT_TOKEN',
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      searchStatus: 'COMPLETED',
      resolution: {
        outcome: 'VERIFIED',
        resultDetails: 'Employment dates and title verified by HR.',
        submittedAt: '2026-07-02T18:00:00.000Z',
      },
      reason: 'Manual verified closeout',
    }),
  },
)

const result = await response.json()

import requests

order_id = "550e8400-e29b-41d4-a716-446655440000"
search_id = "7c7b8f66-7f6a-4b52-9e85-8b3f5b7c1111"
response = requests.patch(
    f"https://sandbox.theary.ai/background-check/v1/orders/{order_id}/searches/{search_id}",
    headers={
        "Authorization": "Bearer YOUR_JWT_TOKEN",
        "Content-Type": "application/json",
    },
    json={
        "searchStatus": "COMPLETED",
        "resolution": {
            "outcome": "VERIFIED",
            "resultDetails": "Employment dates and title verified by HR.",
            "submittedAt": "2026-07-02T18:00:00.000Z",
        },
        "reason": "Manual verified closeout",
    },
)

result = response.json()

Complete As Action Required

curl -sS -X PATCH "https://sandbox.theary.ai/background-check/v1/orders/550e8400-e29b-41d4-a716-446655440000/searches/7c7b8f66-7f6a-4b52-9e85-8b3f5b7c1111" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "searchStatus": "COMPLETED",
    "resolution": {
      "outcome": "ACTION_REQUIRED",
      "reasonCode": "OTHER"
    },
    "reason": "No record found after manual review"
  }'

const orderId = '550e8400-e29b-41d4-a716-446655440000'
const searchId = '7c7b8f66-7f6a-4b52-9e85-8b3f5b7c1111'
const response = await fetch(
  `https://sandbox.theary.ai/background-check/v1/orders/${orderId}/searches/${searchId}`,
  {
    method: 'PATCH',
    headers: {
      Authorization: 'Bearer YOUR_JWT_TOKEN',
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      searchStatus: 'COMPLETED',
      resolution: {
        outcome: 'ACTION_REQUIRED',
        reasonCode: 'OTHER',
      },
      reason: 'No record found after manual review',
    }),
  },
)

const result = await response.json()

import requests

order_id = "550e8400-e29b-41d4-a716-446655440000"
search_id = "7c7b8f66-7f6a-4b52-9e85-8b3f5b7c1111"
response = requests.patch(
    f"https://sandbox.theary.ai/background-check/v1/orders/{order_id}/searches/{search_id}",
    headers={
        "Authorization": "Bearer YOUR_JWT_TOKEN",
        "Content-Type": "application/json",
    },
    json={
        "searchStatus": "COMPLETED",
        "resolution": {
            "outcome": "ACTION_REQUIRED",
            "reasonCode": "OTHER",
        },
        "reason": "No record found after manual review",
    },
)

result = response.json()

Reassign

curl -sS -X PATCH "https://sandbox.theary.ai/background-check/v1/orders/550e8400-e29b-41d4-a716-446655440000/searches/7c7b8f66-7f6a-4b52-9e85-8b3f5b7c1111" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "searchStatus": "REASSIGNED",
    "reason": "Manual operator review requested"
  }'

const orderId = '550e8400-e29b-41d4-a716-446655440000'
const searchId = '7c7b8f66-7f6a-4b52-9e85-8b3f5b7c1111'
const response = await fetch(
  `https://sandbox.theary.ai/background-check/v1/orders/${orderId}/searches/${searchId}`,
  {
    method: 'PATCH',
    headers: {
      Authorization: 'Bearer YOUR_JWT_TOKEN',
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      searchStatus: 'REASSIGNED',
      reason: 'Manual operator review requested',
    }),
  },
)

const result = await response.json()

import requests

order_id = "550e8400-e29b-41d4-a716-446655440000"
search_id = "7c7b8f66-7f6a-4b52-9e85-8b3f5b7c1111"
response = requests.patch(
    f"https://sandbox.theary.ai/background-check/v1/orders/{order_id}/searches/{search_id}",
    headers={
        "Authorization": "Bearer YOUR_JWT_TOKEN",
        "Content-Type": "application/json",
    },
    json={
        "searchStatus": "REASSIGNED",
        "reason": "Manual operator review requested",
    },
)

result = response.json()

Cancel

curl -sS -X PATCH "https://sandbox.theary.ai/background-check/v1/orders/550e8400-e29b-41d4-a716-446655440000/searches/7c7b8f66-7f6a-4b52-9e85-8b3f5b7c1111" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "searchStatus": "CANCELLED",
    "reason": "Applicant withdrew from hiring process"
  }'

const orderId = '550e8400-e29b-41d4-a716-446655440000'
const searchId = '7c7b8f66-7f6a-4b52-9e85-8b3f5b7c1111'
const response = await fetch(
  `https://sandbox.theary.ai/background-check/v1/orders/${orderId}/searches/${searchId}`,
  {
    method: 'PATCH',
    headers: {
      Authorization: 'Bearer YOUR_JWT_TOKEN',
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      searchStatus: 'CANCELLED',
      reason: 'Applicant withdrew from hiring process',
    }),
  },
)

const result = await response.json()

import requests

order_id = "550e8400-e29b-41d4-a716-446655440000"
search_id = "7c7b8f66-7f6a-4b52-9e85-8b3f5b7c1111"
response = requests.patch(
    f"https://sandbox.theary.ai/background-check/v1/orders/{order_id}/searches/{search_id}",
    headers={
        "Authorization": "Bearer YOUR_JWT_TOKEN",
        "Content-Type": "application/json",
    },
    json={
        "searchStatus": "CANCELLED",
        "reason": "Applicant withdrew from hiring process",
    },
)

result = response.json()

Response

success

boolean

Whether the update succeeded.

orderId

string

Parent order identifier.

searchId

string

Updated search identifier.

externalSearchId

string

External system search identifier.

previousStatus

string

Search status before the request.

currentStatus

string

Search status after the request.

orderStatus

string

Parent order status after the update.

orderRollupApplied

boolean

True when this update caused the parent order to roll up to COMPLETED.

webhooksEmitted

string[]

Webhook event types emitted by the request.

Example Response

{
  "success": true,
  "orderId": "550e8400-e29b-41d4-a716-446655440000",
  "searchId": "7c7b8f66-7f6a-4b52-9e85-8b3f5b7c1111",
  "externalSearchId": "EXT-12345",
  "previousStatus": "IN_PROGRESS",
  "currentStatus": "COMPLETED",
  "orderStatus": "COMPLETED",
  "orderRollupApplied": true,
  "webhooksEmitted": ["verification.notification", "verification.completed"]
}

Webhook Behavior

Every status-changing request emits a verification.notification webhook with notificationType: SEARCH_UPDATED. Depending on the target status and resolution, the API may also emit a terminal webhook:

Update	Webhooks emitted
`COMPLETED` with `VERIFIED`, `VERIFIED_DISCREPANCY`, or `VERIFIED_NO_DISCREPANCY`	`verification.notification` (`SEARCH_UPDATED`) and `verification.completed`
`COMPLETED` with `ACTION_REQUIRED`	`verification.notification` (`SEARCH_UPDATED`) and `verification.action_required`
`REASSIGNED`	`verification.notification` (`SEARCH_UPDATED`) and `verification.action_required` with `reasonCode: HUMAN_ESCALATION`
`CANCELLED`	`verification.notification` (`SEARCH_UPDATED`)
Same status as current	No webhook is emitted

The SEARCH_UPDATED notification describes the lifecycle transition. Its metadata includes the previous and current statuses, the changed field, the API trigger, the optional request reason, and any request metadata.

{
  "event": "verification.notification",
  "occurredAt": "2026-07-02T18:00:00.000Z",
  "data": {
    "searchId": "7c7b8f66-7f6a-4b52-9e85-8b3f5b7c1111",
    "externalSearchId": "EXT-12345",
    "searchType": "EMPLOYMENT",
    "notificationType": "SEARCH_UPDATED",
    "metadata": {
      "updatedFields": ["searchStatus"],
      "previousStatus": "IN_PROGRESS",
      "currentStatus": "COMPLETED",
      "source": "api",
      "trigger": "search_update",
      "reason": "Manual verified closeout"
    }
  }
}

For verified closeouts, verification.completed contains the persisted verification result from resolution. For action-required closeouts, verification.action_required contains resolution.reasonCode; reassignment uses HUMAN_ESCALATION. See Webhook Events for complete payload definitions.

Error Responses

Status	Condition
`400`	Invalid request body, missing or invalid `resolution`, or a `resolution` supplied for a non-`COMPLETED` update
`404`	Search was not found for the supplied order
`409`	Request attempts to move a terminal search back to `IN_PROGRESS` or to another terminal status

Overview

Orders API

Search Management

Batches API

Inbound API

Files API

Closeout Events API

Request and order schemas

Webhook schemas

Update Order Search

Update Order Search

Path Parameters

Request Body

Status Transitions

Terminal Side Effects

Order Roll-Up

Example Requests

Complete With a Verification Result

Complete As Action Required

Reassign

Cancel

Response

Example Response

Webhook Behavior

Error Responses

​Update Order Search

​Path Parameters

​Request Body

​Status Transitions

​Terminal Side Effects

​Order Roll-Up

​Example Requests

​Complete With a Verification Result

​Complete As Action Required

​Reassign

​Cancel

​Response

​Example Response

​Webhook Behavior

​Error Responses

Update Order Search

Path Parameters

Request Body

Status Transitions

Terminal Side Effects

Order Roll-Up

Example Requests

Complete With a Verification Result

Complete As Action Required

Reassign

Cancel

Response

Example Response

Webhook Behavior

Error Responses