Manage Outbounds

Use these endpoints when you need to inspect or control outbound verification attempts after an order has already been created. All six routes are scoped to a search within an order.

Pause and resume operations require the search to be IN_PROGRESS. You can list outbounds for a search in any status.

Shared Path Parameters

orderId

string

required

Verification order ID (UUID).

searchId

string

required

Search ID (UUID) within the order.

Get Outbounds

Returns current actionable outbound work for the search.

Returns current actionable outbounds only (those in SCHEDULED, PENDING, or PAUSED status). Sent, delivered, failed, and cancelled records are excluded. Use the returned id as the outboundId when pausing or resuming a single outbound.

Example Request

curl -sS -X GET "https://sandbox.theary.ai/background-check/v1/orders/550e8400-e29b-41d4-a716-446655440000/searches/7c7b8f66-7f6a-4b52-9e85-8b3f5b7c1111/outbounds" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Accept: application/json"

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}/outbounds`, {
  method: 'GET',
  headers: {
    Authorization: 'Bearer YOUR_JWT_TOKEN',
    Accept: 'application/json',
  },
})

const result = await response.json()

import requests

order_id = "550e8400-e29b-41d4-a716-446655440000"
search_id = "7c7b8f66-7f6a-4b52-9e85-8b3f5b7c1111"

response = requests.get(
    f"https://sandbox.theary.ai/background-check/v1/orders/{order_id}/searches/{search_id}/outbounds",
    headers={
        "Authorization": "Bearer YOUR_JWT_TOKEN",
        "Accept": "application/json",
    },
)

result = response.json()

Response

success

boolean

searchId

string

externalSearchId

string | null

outbounds

array

Current actionable outbound activities and contact attempts for the search.

Outbound Item Fields

string

Outbound identifier. Activity records use their UUID. Contact attempts without a matching activity use attempt-<contactAttemptUuid>.

contactId

string | null

Contact associated with the outbound, when available.

contactName

string | null

Contact name associated with the outbound, when available.

entityName

string | null

Entity being contacted.

channel

string

Outbound channel, such as EMAIL, FAX, VOICE, or a system method.

channelValue

string

Destination for the outbound, such as an email address or fax number.

description

string | null

Human-readable activity description.

metadata

object

Additional status, scheduling, cancellation, or system metadata.

createdAt

string

Activity or attempt creation timestamp.

scheduledAt

string | null

Scheduled outbound time when the outbound is pending, scheduled, or paused.

sentAt

string | null

Send timestamp when the outbound has been sent.

status

string

Current actionable status: SCHEDULED, PENDING, or PAUSED.

attemptNumber

number | null

Attempt number when available.

attemptNumberSearch

number | null

Attempt sequence across all outbound attempts for the search.

attemptNumberContact

number | null

Attempt sequence for this contact.

attemptNumberChannel

number | null

Attempt sequence for this channel.

isCancelled

boolean

Whether this outbound is cancelled.

cancellationReason

string

Cancellation reason when available.

failureReason

string

Failure reason when available.

Example Response

{
  "success": true,
  "searchId": "6ba7b810-9dad-11d1-80b4-00c04fd430c8",
  "externalSearchId": "EXT-12345",
  "outbounds": [
    {
      "id": "attempt-e8c015f6-3866-4226-827f-e8e86328ef29",
      "contactId": "996bf751-05b9-424b-8217-44de7742decd",
      "contactName": "HR Department",
      "entityName": "Acme Corporation",
      "channel": "EMAIL",
      "channelValue": "hr@acme.com",
      "description": "System outbound attempt #1",
      "metadata": {
        "source": "system",
        "outcome": "SCHEDULED"
      },
      "createdAt": "2026-06-25T21:41:16.644Z",
      "scheduledAt": "2026-06-25T21:41:16.644Z",
      "sentAt": null,
      "status": "SCHEDULED",
      "attemptNumber": 1,
      "attemptNumberSearch": 1,
      "attemptNumberContact": 1,
      "attemptNumberChannel": 1,
      "isCancelled": false
    }
  ]
}

Cancel Outbounds

Permanently cancels pending outbound work without cancelling the search itself.

Request Body

contactDestination

string

Optional contact destination. When provided, only pending outbound matching this normalized destination is cancelled.

Example Request

curl -sS -X POST "https://sandbox.theary.ai/background-check/v1/orders/550e8400-e29b-41d4-a716-446655440000/searches/7c7b8f66-7f6a-4b52-9e85-8b3f5b7c1111/cancel-outbounds" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "contactDestination": "hr@acme.com"
  }'

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}/cancel-outbounds`,
  {
    method: 'POST',
    headers: {
      Authorization: 'Bearer YOUR_JWT_TOKEN',
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({ contactDestination: 'hr@acme.com' }),
  },
)

const result = await response.json()

import requests

order_id = "550e8400-e29b-41d4-a716-446655440000"
search_id = "7c7b8f66-7f6a-4b52-9e85-8b3f5b7c1111"

response = requests.post(
    f"https://sandbox.theary.ai/background-check/v1/orders/{order_id}/searches/{search_id}/cancel-outbounds",
    headers={
        "Authorization": "Bearer YOUR_JWT_TOKEN",
        "Content-Type": "application/json",
    },
    json={"contactDestination": "hr@acme.com"},
)

result = response.json()

Behavior

Cancels all pending outbound work — scheduled contact attempts and matching unsent outbound records. When contactDestination is provided, cancellation is scoped to pending outbound matching that normalized destination.

Cancellation is permanent. Resume operations do not recreate cancelled outbound. Cancelling while paused clears pause state and marks paused attempts as CANCELLED.

Pause Outbounds

Pauses all pending outbound work for the search.

Request Body

reason

string

Optional pause reason stored in outbound control metadata and webhook payloads.

Example Request

curl -sS -X POST "https://sandbox.theary.ai/background-check/v1/orders/550e8400-e29b-41d4-a716-446655440000/searches/7c7b8f66-7f6a-4b52-9e85-8b3f5b7c1111/pause-outbounds" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "reason": "Entity HR department closed for holiday"
  }'

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}/pause-outbounds`,
  {
    method: 'POST',
    headers: {
      Authorization: 'Bearer YOUR_JWT_TOKEN',
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({ reason: 'Entity HR department closed for holiday' }),
  },
)

const result = await response.json()

import requests

order_id = "550e8400-e29b-41d4-a716-446655440000"
search_id = "7c7b8f66-7f6a-4b52-9e85-8b3f5b7c1111"

response = requests.post(
    f"https://sandbox.theary.ai/background-check/v1/orders/{order_id}/searches/{search_id}/pause-outbounds",
    headers={
        "Authorization": "Bearer YOUR_JWT_TOKEN",
        "Content-Type": "application/json",
    },
    json={"reason": "Entity HR department closed for holiday"},
)

result = response.json()

Behavior

pause-outbounds affects pending outbound work only. It pauses:

SCHEDULED contact attempts
TRIGGERED_BY_SCHEDULER contact attempts that have been claimed but not completed
pending delayed or queued outbound jobs
matching unsent outbound activity records, when a corresponding activity can be identified

Already sent, delivered, failed, cancelled, or superseded activity history is not changed. Calling pause-outbounds again while the search is already paused is idempotent and returns a successful response with previousOutboundStatus set to PAUSED.

Repeating a pause when the search is already paused succeeds without changing state or emitting another webhook.

Pause Outbound

Pauses one pending outbound while leaving the search-level outbound control status ACTIVE.

Request Body

outboundId

string

required

Outbound activity ID, contact attempt ID, or attempt- prefixed contact attempt ID. Use GET .../outbounds to discover this value.

reason

string

Optional pause reason stored in outbound control metadata and webhook payloads.

Example Request

curl -sS -X POST "https://sandbox.theary.ai/background-check/v1/orders/550e8400-e29b-41d4-a716-446655440000/searches/7c7b8f66-7f6a-4b52-9e85-8b3f5b7c1111/pause-outbound" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "outboundId": "attempt-e8c015f6-3866-4226-827f-e8e86328ef29",
    "reason": "Pause this specific outbound while contact details are reviewed"
  }'

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}/pause-outbound`,
  {
    method: 'POST',
    headers: {
      Authorization: 'Bearer YOUR_JWT_TOKEN',
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      outboundId: 'attempt-e8c015f6-3866-4226-827f-e8e86328ef29',
      reason: 'Pause this specific outbound while contact details are reviewed',
    }),
  },
)

const result = await response.json()

import requests

order_id = "550e8400-e29b-41d4-a716-446655440000"
search_id = "7c7b8f66-7f6a-4b52-9e85-8b3f5b7c1111"

response = requests.post(
    f"https://sandbox.theary.ai/background-check/v1/orders/{order_id}/searches/{search_id}/pause-outbound",
    headers={
        "Authorization": "Bearer YOUR_JWT_TOKEN",
        "Content-Type": "application/json",
    },
    json={
        "outboundId": "attempt-e8c015f6-3866-4226-827f-e8e86328ef29",
        "reason": "Pause this specific outbound while contact details are reviewed",
    },
)

result = response.json()

Behavior

pause-outbound affects only the matching pending outbound. The search-level outbound control status remains ACTIVE, so other pending outbound attempts for the same search can continue. The endpoint accepts an activity UUID, a contact attempt UUID, or attempt-<contactAttemptUuid>. Already sent, delivered, failed, cancelled, or superseded history is not changed.

Resume Outbounds

Restores paused outbound work to an active scheduled state.

Request Body

reason

string

Optional resume reason stored in outbound control metadata and webhook payloads.

Example Request

curl -sS -X POST "https://sandbox.theary.ai/background-check/v1/orders/550e8400-e29b-41d4-a716-446655440000/searches/7c7b8f66-7f6a-4b52-9e85-8b3f5b7c1111/resume-outbounds" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "reason": "Entity HR department reopened"
  }'

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}/resume-outbounds`,
  {
    method: 'POST',
    headers: {
      Authorization: 'Bearer YOUR_JWT_TOKEN',
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({ reason: 'Entity HR department reopened' }),
  },
)

const result = await response.json()

import requests

order_id = "550e8400-e29b-41d4-a716-446655440000"
search_id = "7c7b8f66-7f6a-4b52-9e85-8b3f5b7c1111"

response = requests.post(
    f"https://sandbox.theary.ai/background-check/v1/orders/{order_id}/searches/{search_id}/resume-outbounds",
    headers={
        "Authorization": "Bearer YOUR_JWT_TOKEN",
        "Content-Type": "application/json",
    },
    json={"reason": "Entity HR department reopened"},
)

result = response.json()

Behavior

resume-outbounds restores paused outbound work to an active scheduled state. It resumes:

attempts paused by pause-outbounds
attempts paused individually via the single-outbound endpoint
delayed outbound jobs captured in the pause snapshot
matching activity metadata, with the pause marker removed and a resume marker added

Attempts whose original scheduled time is already in the past are restored with an immediate scheduled time so the scheduler can process them on the next run. Permanently cancelled or superseded attempts are not recreated. Calling resume-outbounds when there is no paused outbound state is idempotent and returns a successful response with previousOutboundStatus set to ACTIVE.

Repeating a resume when no paused state exists succeeds without changing state or emitting another webhook. Permanently cancelled and superseded attempts are never recreated.

Resume Outbound

Restores one paused outbound identified by outboundId.

Request Body

outboundId

string

required

Outbound activity ID, contact attempt ID, or attempt- prefixed contact attempt ID. Use GET .../outbounds to discover this value.

reason

string

Optional resume reason stored in outbound control metadata and webhook payloads.

Example Request

curl -sS -X POST "https://sandbox.theary.ai/background-check/v1/orders/550e8400-e29b-41d4-a716-446655440000/searches/7c7b8f66-7f6a-4b52-9e85-8b3f5b7c1111/resume-outbound" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "outboundId": "attempt-e8c015f6-3866-4226-827f-e8e86328ef29",
    "reason": "Resume this specific outbound"
  }'

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}/resume-outbound`,
  {
    method: 'POST',
    headers: {
      Authorization: 'Bearer YOUR_JWT_TOKEN',
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      outboundId: 'attempt-e8c015f6-3866-4226-827f-e8e86328ef29',
      reason: 'Resume this specific outbound',
    }),
  },
)

const result = await response.json()

import requests

order_id = "550e8400-e29b-41d4-a716-446655440000"
search_id = "7c7b8f66-7f6a-4b52-9e85-8b3f5b7c1111"

response = requests.post(
    f"https://sandbox.theary.ai/background-check/v1/orders/{order_id}/searches/{search_id}/resume-outbound",
    headers={
        "Authorization": "Bearer YOUR_JWT_TOKEN",
        "Content-Type": "application/json",
    },
    json={
        "outboundId": "attempt-e8c015f6-3866-4226-827f-e8e86328ef29",
        "reason": "Resume this specific outbound",
    },
)

result = response.json()

Behavior

resume-outbound restores only the paused outbound tracked for the supplied outboundId. If the original scheduled time is already in the past, the attempt is restored with an immediate scheduled time so the scheduler can process it on the next run. Calling resume-outbound when the supplied outbound is not paused is idempotent and returns a successful response with previousOutboundStatus set to ACTIVE.

Repeating this request for an outbound that is already active succeeds without changing state or emitting another webhook.

Mutation Response

success

boolean

Whether the request was processed.

searchId

string

Internal search UUID.

externalSearchId

string

External search identifier when present.

outboundId

string

Single-outbound response only. The outbound identifier supplied in the request.

action

string

PAUSE_OUTBOUND or RESUME_OUTBOUND.

previousOutboundStatus

string

Previous outbound control status: ACTIVE or PAUSED.

currentOutboundStatus

string

Current outbound control status: ACTIVE or PAUSED. For single-outbound pauses, this remains ACTIVE because the search is not globally paused.

cancelledCount

number

Cancel response only. Number of pending outbound jobs plus contact attempts cancelled.

cancelledActivities

number

Cancel response only. Number of outbound activity records marked as cancelled.

pausedCount

number

Pause response only. Number of queue jobs plus contact attempts paused.

pausedActivities

number

Pause response only. Number of outbound activity records marked as paused.

resumedCount

number

Resume response only. Number of queue jobs plus contact attempts restored.

resumedActivities

number

Resume response only. Number of outbound activity records marked as resumed.

outbounds

array

Search-level pause/resume response. Outbound attempts paused or resumed by this request. Each item includes id, method, contactId, attemptDate, and destination.

message

string

Human-readable summary of the action taken.

Search-Level Pause/Resume Response Shape

{
  "outbounds": [
    {
      "id": "17333f98-0226-4142-a8cb-bbb9af936795",
      "method": "THIRD_PARTY_PENDING",
      "contactId": null,
      "attemptDate": "2026-06-25T21:41:16.461Z",
      "destination": null
    },
    {
      "id": "e8c015f6-3866-4226-827f-e8e86328ef29",
      "method": "EMAIL",
      "contactId": "996bf751-05b9-424b-8217-44de7742decd",
      "attemptDate": "2026-06-25T21:41:16.644Z",
      "destination": "hr@acme.com"
    }
  ]
}

Webhook Behavior

Only successful pause and resume operations that change outbound state emit a verification.notification webhook. Listing or cancelling outbounds does not emit an outbound-control notification, and idempotent pause or resume requests do not emit a duplicate event.

Operation	`notificationType`
Pause one outbound	`OUTBOUND_PAUSED`
Pause all outbounds	`OUTBOUNDS_PAUSED`
Resume one outbound	`OUTBOUND_RESUMED`
Resume all outbounds	`OUTBOUNDS_RESUMED`

The webhook includes an outboundControl object with:

action: PAUSE_OUTBOUND or RESUME_OUTBOUND
outboundId: the requested outbound ID for single-outbound operations
reason: the optional reason supplied in the request
count: number of outbound items paused or resumed
activitiesMarked: number of activity records marked as paused or resumed
trigger: api
outbounds: affected outbound summaries for search-level operations

{
  "event": "verification.notification",
  "occurredAt": "2026-06-25T21:42:00.000Z",
  "data": {
    "searchId": "7c7b8f66-7f6a-4b52-9e85-8b3f5b7c1111",
    "externalSearchId": "EXT-12345",
    "searchType": "EMPLOYMENT",
    "notificationType": "OUTBOUNDS_PAUSED",
    "outboundControl": {
      "action": "PAUSE_OUTBOUND",
      "reason": "Entity HR department closed for holiday",
      "count": 2,
      "activitiesMarked": 2,
      "trigger": "api",
      "outbounds": [
        {
          "id": "e8c015f6-3866-4226-827f-e8e86328ef29",
          "method": "EMAIL",
          "contactId": "996bf751-05b9-424b-8217-44de7742decd",
          "attemptDate": "2026-06-25T21:41:16.644Z",
          "destination": "hr@acme.com"
        }
      ]
    }
  }
}

GET .../outbounds and cancel-outbounds do not emit outbound-control webhook notifications. See Webhook Events for the complete payload definition.

Additional Behavior

contactDestination scoping is supported for cancel operations. Pause and resume always apply to all pending outbound (or a single outbound when using the single-outbound endpoints).
If a replacement outbound supersedes a paused outbound, the old attempt is marked as superseded and is not recreated on resume.
Use Manage Search Contacts to inspect or update the contact plan.

​Manage Outbounds

​Shared Path Parameters

​Get Outbounds

​Example Request

​Response

​Outbound Item Fields

​Example Response

​Cancel Outbounds

​Request Body

​Example Request

​Behavior

​Pause Outbounds

​Request Body

​Example Request

​Behavior

​Pause Outbound

​Request Body

​Example Request

​Behavior

​Resume Outbounds

​Request Body

​Example Request

​Behavior

​Resume Outbound

​Request Body

​Example Request

​Behavior

​Mutation Response

​Search-Level Pause/Resume Response Shape

​Webhook Behavior

​Additional Behavior

Manage Outbounds

Shared Path Parameters

Get Outbounds

Example Request

Response

Outbound Item Fields

Example Response

Cancel Outbounds

Request Body

Example Request

Behavior

Pause Outbounds

Request Body

Example Request

Behavior

Pause Outbound

Request Body

Example Request

Behavior

Resume Outbounds

Request Body

Example Request

Behavior

Resume Outbound

Request Body

Example Request

Behavior

Mutation Response

Search-Level Pause/Resume Response Shape

Webhook Behavior

Additional Behavior