Cancel scheduled outbound activities

curl --request POST \
  --url https://sandbox.theary.ai/background-check/v1/searches/cancel-activities \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "searchId": "123e4567-e89b-12d3-a456-426614174000",
  "contactDestination": "hr@techcorp.com"
}
'

import requests

url = "https://sandbox.theary.ai/background-check/v1/searches/cancel-activities"

payload = {
    "searchId": "123e4567-e89b-12d3-a456-426614174000",
    "contactDestination": "hr@techcorp.com"
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    searchId: '123e4567-e89b-12d3-a456-426614174000',
    contactDestination: 'hr@techcorp.com'
  })
};

fetch('https://sandbox.theary.ai/background-check/v1/searches/cancel-activities', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://sandbox.theary.ai/background-check/v1/searches/cancel-activities",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'searchId' => '123e4567-e89b-12d3-a456-426614174000',
    'contactDestination' => 'hr@techcorp.com'
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://sandbox.theary.ai/background-check/v1/searches/cancel-activities"

	payload := strings.NewReader("{\n  \"searchId\": \"123e4567-e89b-12d3-a456-426614174000\",\n  \"contactDestination\": \"hr@techcorp.com\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://sandbox.theary.ai/background-check/v1/searches/cancel-activities")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"searchId\": \"123e4567-e89b-12d3-a456-426614174000\",\n  \"contactDestination\": \"hr@techcorp.com\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://sandbox.theary.ai/background-check/v1/searches/cancel-activities")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"searchId\": \"123e4567-e89b-12d3-a456-426614174000\",\n  \"contactDestination\": \"hr@techcorp.com\"\n}"

response = http.request(request)
puts response.read_body

{
  "statusCode": 400,
  "message": ["Provide exactly one of searchId or externalSearchId"],
  "error": "Bad Request"
}

POST

background-check

searches

cancel-activities

Cancel scheduled outbound activities

curl --request POST \
  --url https://sandbox.theary.ai/background-check/v1/searches/cancel-activities \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "searchId": "123e4567-e89b-12d3-a456-426614174000",
  "contactDestination": "hr@techcorp.com"
}
'

import requests

url = "https://sandbox.theary.ai/background-check/v1/searches/cancel-activities"

payload = {
    "searchId": "123e4567-e89b-12d3-a456-426614174000",
    "contactDestination": "hr@techcorp.com"
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    searchId: '123e4567-e89b-12d3-a456-426614174000',
    contactDestination: 'hr@techcorp.com'
  })
};

fetch('https://sandbox.theary.ai/background-check/v1/searches/cancel-activities', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://sandbox.theary.ai/background-check/v1/searches/cancel-activities",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'searchId' => '123e4567-e89b-12d3-a456-426614174000',
    'contactDestination' => 'hr@techcorp.com'
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://sandbox.theary.ai/background-check/v1/searches/cancel-activities"

	payload := strings.NewReader("{\n  \"searchId\": \"123e4567-e89b-12d3-a456-426614174000\",\n  \"contactDestination\": \"hr@techcorp.com\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://sandbox.theary.ai/background-check/v1/searches/cancel-activities")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"searchId\": \"123e4567-e89b-12d3-a456-426614174000\",\n  \"contactDestination\": \"hr@techcorp.com\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://sandbox.theary.ai/background-check/v1/searches/cancel-activities")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"searchId\": \"123e4567-e89b-12d3-a456-426614174000\",\n  \"contactDestination\": \"hr@techcorp.com\"\n}"

response = http.request(request)
puts response.read_body

{
  "statusCode": 400,
  "message": ["Provide exactly one of searchId or externalSearchId"],
  "error": "Bad Request"
}

Cancel Search Activities

Cancels all pending/scheduled outbound activities (email, voice, fax) for a search — pending outbound jobs, scheduled contact attempts, and existing activity records are cancelled or marked cancelled. Identify the search by internal searchId or externalSearchId, and optionally restrict cancellation to a single contactDestination.

Request

searchId

string

Internal search identifier (UUID). Provide exactly one of searchId or externalSearchId.

externalSearchId

string

External search identifier. Provide exactly one of searchId or externalSearchId.

contactDestination

string

Optional. Only cancel activities directed at this specific contact destination (email address or phone number). When omitted, all pending activities for the search are cancelled. When provided, it cannot be empty or whitespace-only.

Response

success

boolean

Whether cancellation succeeded.

searchId

string

Resolved internal search identifier. On failure paths this may instead echo the searchId or externalSearchId you sent, before resolution.

externalSearchId

string

External search identifier for the resolved search. Present on success and on some failure paths; may be null.

cancelledCount

number

Total number of pending outbound jobs and scheduled contact attempts cancelled. Present only on success.

cancelledActivities

number

Number of existing activity records marked as cancelled. Present only on success.

message

string

Human-readable summary of what was cancelled. Present only on success.

error

string

Reason cancellation did not succeed. Present only when success is false.

Failures such as “search not found” are represented in the response body with success: false and HTTP 200 — they are not surfaced as 404. Only request validation failures (missing/duplicate identifiers, blank contactDestination) return a 400.

Example Request

curl -sS -X POST "https://sandbox.theary.ai/background-check/v1/searches/cancel-activities" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "searchId": "123e4567-e89b-12d3-a456-426614174000",
    "contactDestination": "hr@techcorp.com"
  }'

const response = await fetch('https://sandbox.theary.ai/background-check/v1/searches/cancel-activities', {
  method: 'POST',
  headers: {
    Authorization: 'Bearer YOUR_JWT_TOKEN',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    searchId: '123e4567-e89b-12d3-a456-426614174000',
    contactDestination: 'hr@techcorp.com',
  }),
})

const result = await response.json()

import requests

response = requests.post(
    'https://sandbox.theary.ai/background-check/v1/searches/cancel-activities',
    headers={
        'Authorization': 'Bearer YOUR_JWT_TOKEN',
        'Content-Type': 'application/json',
    },
    json={
        "searchId": "123e4567-e89b-12d3-a456-426614174000",
        "contactDestination": "hr@techcorp.com",
    },
)

result = response.json()

Example Response

{
  "success": true,
  "searchId": "123e4567-e89b-12d3-a456-426614174000",
  "externalSearchId": "client-emp-001",
  "cancelledCount": 2,
  "cancelledActivities": 3,
  "message": "Cancelled 2 pending outbound activities and marked 3 existing activity records as cancelled"
}

Search not found (200, success: false):

{
  "success": false,
  "searchId": "123e4567-e89b-12d3-a456-426614174000",
  "error": "Search not found"
}

Error Responses

{
  "statusCode": 400,
  "message": ["Provide exactly one of searchId or externalSearchId"],
  "error": "Bad Request"
}

{
  "statusCode": 400,
  "message": ["contactDestination cannot be empty or whitespace"],
  "error": "Bad Request"
}

{
  "statusCode": 401,
  "message": "Unauthorized"
}

Use Cases

Stop outreach after resolution outside the system: Cancel remaining scheduled attempts once a search is resolved through another channel.
Contact-specific suppression: Cancel only the activities targeting a contact who has asked not to be contacted further, via contactDestination.

Authorizations

Authorization

string

header

required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Body

application/json

searchId

string

The internal search ID (UUID) to cancel activities for

Example:

"123e4567-e89b-12d3-a456-426614174000"

externalSearchId

string

The external search ID (client reference ID) to cancel activities for

Example:

"12345678"

contactDestination

string

Optional: Only cancel activities to this specific contact destination (email/phone)

Example:

"contact@example.com"

Response

201 - application/json

The response is of type object.

Get Search by External ID Create Batch Order

Overview

Orders API

Batches API

Inbound API

Files API

Closeout Events API

Request and order schemas

Webhook schemas

Cancel Search Activities

Cancel Search Activities

Request

Response

Example Request

Example Response

Error Responses

Use Cases

Authorizations

Body

Response

​Cancel Search Activities

​Request

​Response

​Example Request

​Example Response

​Error Responses

​Use Cases

Authorizations

Body

Response

Cancel Search Activities

Request

Response

Example Request

Example Response

Error Responses

Use Cases