> ## Documentation Index
> Fetch the complete documentation index at: https://documentation.theary.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Cancel Search Activities

> Cancel all pending or scheduled outbound activities for a search

# 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

<ParamField body="searchId" type="string">
  Internal search identifier (UUID). Provide **exactly one** of `searchId` or `externalSearchId`.
</ParamField>

<ParamField body="externalSearchId" type="string">
  External search identifier. Provide **exactly one** of `searchId` or `externalSearchId`.
</ParamField>

<ParamField body="contactDestination" type="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.
</ParamField>

## Response

<ResponseField name="success" type="boolean">
  Whether cancellation succeeded.
</ResponseField>

<ResponseField name="searchId" type="string">
  Resolved internal search identifier. On failure paths this may instead echo the `searchId` or `externalSearchId` you sent, before resolution.
</ResponseField>

<ResponseField name="externalSearchId" type="string">
  External search identifier for the resolved search. Present on success and on some failure paths; may be `null`.
</ResponseField>

<ResponseField name="cancelledCount" type="number">
  Total number of pending outbound jobs and scheduled contact attempts cancelled. Present only on success.
</ResponseField>

<ResponseField name="cancelledActivities" type="number">
  Number of existing activity records marked as cancelled. Present only on success.
</ResponseField>

<ResponseField name="message" type="string">
  Human-readable summary of what was cancelled. Present only on success.
</ResponseField>

<ResponseField name="error" type="string">
  Reason cancellation did not succeed. Present only when `success` is `false`.
</ResponseField>

<Note>
  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`.
</Note>

## Example Request

<CodeGroup>
  ```bash cURL theme={null}
  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"
    }'
  ```

  ```javascript JavaScript theme={null}
  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()
  ```

  ```python Python theme={null}
  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()
  ```
</CodeGroup>

## Example Response

```json theme={null}
{
  "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):**

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

## Error Responses

<ResponseExample>
  ```json 400 - Both or neither identifier provided theme={null}
  {
    "statusCode": 400,
    "message": ["Provide exactly one of searchId or externalSearchId"],
    "error": "Bad Request"
  }
  ```
</ResponseExample>

<ResponseExample>
  ```json 400 - Blank contactDestination theme={null}
  {
    "statusCode": 400,
    "message": ["contactDestination cannot be empty or whitespace"],
    "error": "Bad Request"
  }
  ```
</ResponseExample>

<ResponseExample>
  ```json 401 Unauthorized theme={null}
  {
    "statusCode": 401,
    "message": "Unauthorized"
  }
  ```
</ResponseExample>

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


## OpenAPI

````yaml POST /background-check/v1/searches/cancel-activities
openapi: 3.0.0
info:
  title: SNH AI Background Check API
  description: >-
    AI-powered agentic background verification service for employment and
    education checks.
  version: '1.0'
  contact: {}
servers:
  - url: https://sandbox.theary.ai
    description: Sandbox
  - url: https://api.theary.ai
    description: Production
  - url: http://localhost:3000
    description: Local development
security:
  - bearerAuth: []
tags: []
paths:
  /background-check/v1/searches/cancel-activities:
    post:
      tags:
        - Searches
      summary: Cancel scheduled outbound activities
      description: >-
        Cancels all pending/scheduled outbound activities for a search. Provide
        either searchId (internal UUID) or externalSearchId (client reference
        ID). Optionally filter by contact destination.
      operationId: cancel-activities
      parameters: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CancelActivitiesDto'
            examples:
              cancelBySearchId:
                value:
                  searchId: 123e4567-e89b-12d3-a456-426614174000
                  contactDestination: hr@techcorp.com
      responses:
        '201':
          description: ''
          content:
            application/json:
              schema:
                type: object
      security:
        - bearerAuth: []
components:
  schemas:
    CancelActivitiesDto:
      type: object
      properties:
        searchId:
          type: string
          description: The internal search ID (UUID) to cancel activities for
          example: 123e4567-e89b-12d3-a456-426614174000
        externalSearchId:
          type: string
          description: >-
            The external search ID (client reference ID) to cancel activities
            for
          example: '12345678'
        contactDestination:
          type: string
          description: >-
            Optional: Only cancel activities to this specific contact
            destination (email/phone)
          example: contact@example.com
      title: Cancel Activities
  securitySchemes:
    bearerAuth:
      scheme: bearer
      bearerFormat: JWT
      type: http

````