Error
A valid request URL is required to generate request examples{
"statusCode": 400,
"message": ["Provide exactly one of searchId or externalSearchId"],
"error": "Bad Request"
}
Orders API
Cancel Search Activities
Cancel all pending or scheduled outbound activities for a search. Kept for glue backwards compatibility; This endpoint will be deprecated once glue migration is complete.
POST
/
background-check
/
v1
/
searches
/
cancel-activities
Error
A valid request URL is required to generate request examples{
"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 internalsearchId or externalSearchId, and optionally restrict cancellation to a single contactDestination.
Kept for backwards compatibility (for example glue integrations). New integrations should prefer the order-scoped
cancel-outbounds endpoint. This endpoint will be deprecated once
glue migration is complete.Request
string
Internal search identifier (UUID). Provide exactly one of
searchId or externalSearchId.string
External search identifier. Provide exactly one of
searchId or externalSearchId.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
boolean
Whether cancellation succeeded.
string
Resolved internal search identifier. On failure paths this may instead echo the
searchId or externalSearchId you sent,
before resolution.string
External search identifier for the resolved search. Present on success and on some failure paths; may be
null.number
Total number of pending outbound jobs and scheduled contact attempts cancelled. Present only on success.
number
Number of existing activity records marked as cancelled. Present only on success.
string
Human-readable summary of what was cancelled. Present only on success.
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"
}
{
"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.
Body
application/json
The internal search ID (UUID) to cancel activities for
Example:
"123e4567-e89b-12d3-a456-426614174000"
The external search ID (UBS refId) to cancel activities for
Example:
"12345678"
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.