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.

For backwards compatibility, glue and other integrators can still call POST /background-check/v1/searches/cancel-activities with searchId or externalSearchId in the body. Prefer the order-scoped cancel-outbounds route for new integrations. This endpoint will be deprecated once glue migration is complete.

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

Shared Path Parameters

string

required

Verification order ID (UUID).

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

boolean

string

string | null

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>.

string | null

Contact associated with the outbound, when available.

string | null

Contact name associated with the outbound, when available.

string | null

Entity being contacted.

string

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

string

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

string | null

Human-readable activity description.

object

Additional status, scheduling, cancellation, or system metadata.

string

Activity or attempt creation timestamp.

string | null

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

string | null

Send timestamp when the outbound has been sent.

string

Current actionable status: SCHEDULED, PENDING, or PAUSED.

number | null

Attempt number when available.

number | null

Attempt sequence across all outbound attempts for the search.

number | null

Attempt sequence for this contact.

number | null

Attempt sequence for this channel.

boolean

Whether this outbound is cancelled.

string

Cancellation reason when available.

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

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

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 pauses the pending outbound work that exists at the moment of the call. 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. While the search-level outbound status is PAUSED, automated outbound stays on hold: the workflow does not send and inbound replies do not schedule the next contact attempt. Outbound you schedule explicitly after the pause — through the scheduling endpoints or the Driver’s Seat — is created live and sends on its own schedule. Call pause-outbounds again to capture that newer work; each call takes a fresh snapshot of whatever is pending at that time. Calling pause-outbounds when the search is already paused and nothing new is pending is idempotent and returns a successful response with previousOutboundStatus set to PAUSED.

Repeating a pause when the search is already paused and no new outbound has been scheduled since 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

string

required

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

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. It does not change the search-level outbound control status, so other pending outbound attempts for the same search can continue. This works while the search is globally paused too: an outbound that is still live is paused on its own, and one that the search-level pause already holds is reported as already paused with currentOutboundStatus: PAUSED. An unknown outboundId is rejected. 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

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. resume-outbounds also returns the search-level status to ACTIVE, which re-enables automated outbound. 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

string

required

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

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, whether it was paused individually or by pause-outbounds. 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. If this was the last paused outbound on a globally paused search, the search-level hold is released as well: the response reports clearedSearchPause: true and currentOutboundStatus: ACTIVE, any outbound jobs still held by the pause are re-enqueued, and an OUTBOUNDS_RESUMED webhook is emitted alongside OUTBOUND_RESUMED. A search never stays paused with nothing paused under it. Cancelling the last paused outbound releases the hold the same way. 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

boolean

Whether the request was processed.

string

Internal search UUID.

string

External search identifier when present.

string

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

string

PAUSE_OUTBOUND or RESUME_OUTBOUND.

string

Previous outbound control status: ACTIVE or PAUSED.

string

Current outbound control status: ACTIVE or PAUSED. A single-outbound pause does not change it. A single-outbound resume or cancel leaves it PAUSED while other outbounds are still held, and reports ACTIVE once it released the last one.

boolean

Single-outbound resume and cancel responses only. true when this request released the last paused outbound and returned the search-level status to ACTIVE.

number

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

number

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

number

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

number

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

number

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

array

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

string

Human-readable summary of the action taken.

Search-Level Pause/Resume Response Shape

{
  "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"
    }
  ]
}

Webhook Behavior

Only successful pause, resume, and cancel operations that change outbound state emit a verification.notification webhook. Listing outbounds does not emit an outbound-control notification, and idempotent pause, resume, or cancel 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`
Cancel outbounds	`OUTBOUNDS_CANCELLED`

Resuming or cancelling the last paused outbound emits OUTBOUNDS_RESUMED in addition to the single-outbound event, because the search-level hold is released by that request. The webhook includes an outboundControl object with:

action: PAUSE_OUTBOUND, RESUME_OUTBOUND, or CANCEL_OUTBOUND
outboundId: the requested outbound ID for single-outbound operations
reason: the optional reason supplied in the request
count: number of contact-backed outbound items paused, resumed, or cancelled (matches outbounds for search-level operations; excludes scheduler timer rows)
activitiesMarked: number of activity records marked as paused, resumed, or cancelled
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": 1,
      "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 does 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).
A search-level pause holds the outbound that was pending when you called it and blocks automated outbound. Outbound you schedule after that call is live; pause again to hold it too.
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