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.

string

required

Search UUID within the order.

Request Body

string

required

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

object

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

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.

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

string | object

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

string

Optional submission timestamp for verified outcomes.

object

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

string

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

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

boolean

Whether the update succeeded.

string

Parent order identifier.

string

Updated search identifier.

string

External system search identifier.

string

Search status before the request.

string

Search status after the request.

string

Parent order status after the update.

boolean

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

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

Path Parameters

string

required

Verification order ID (UUID)

searchId

string

required

Search ID (UUID)

Body

application/json

searchStatus

enum<string>

required

Search status to apply. V1 supports status updates only.

Available options:

IN_PROGRESS,

COMPLETED,

CANCELLED,

REASSIGNED

Example:

"COMPLETED"

resolution

object

Terminal resolution for COMPLETED updates. Use a verified outcome with result details, or ACTION_REQUIRED with reasonCode.

Show child attributes

reason

string

Human-readable reason for the update

Example:

"Manual verified closeout"

metadata

object

Additional metadata included in update notification and terminal webhook context

Response

200 - application/json

Search updated

success

boolean

required

Example:

true

orderId

string

required

Parent order ID

searchId

string

required

Search ID

previousStatus

enum<string>

required

Available options:

IN_PROGRESS,

COMPLETED,

CANCELLED,

REASSIGNED

currentStatus

enum<string>

required

Available options:

IN_PROGRESS,

COMPLETED,

CANCELLED,

REASSIGNED

orderStatus

string

required

Parent order status after the update

Example:

"COMPLETED"

orderRollupApplied

boolean

required

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

webhooksEmitted

string[]

required

Webhook event types emitted by this request

externalSearchId

string

External search ID, when present

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

Path Parameters

Body

Response

​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

Path Parameters

Body

Response

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