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

# Cancel Queued Call

> Cancel a pending call in the queue for a given phone number

## API Endpoint

```bash theme={null}
POST https://app.sawt.sa/api/v1/calls/queue/cancel/{phoneNumber}
```

## Path Parameters

<ParamField path="phoneNumber" type="string" required>
  The phone number of the queued call to cancel (e.g., "966501234567"). Accepts numbers with or without the "+" or "966"/"0" prefix — they are normalized automatically.
</ParamField>

## Request Headers

<ParamField header="Authorization" required>
  Bearer your-api-key
</ParamField>

<ParamField header="Content-Type">
  application/json
</ParamField>

## Request Body

<ParamField body="agentId" type="string">
  Optional agent ID to scope the cancellation to a specific agent's queue. If provided, must be a valid agent belonging to your company.
</ParamField>

<Accordion title="Example Request">
  ```json theme={null}
  {
    "agentId": "e63355c6-cf51-40f3-b006-b615d9ab762d"
  }
  ```
</Accordion>

<Note>
  The request body is optional — an empty body is valid if you don't need to scope by `agentId`.
</Note>

## Response

<ResponseField name="success" type="boolean" required>
  Whether the request was processed successfully
</ResponseField>

<ResponseField name="data" type="object" required>
  Cancellation result object containing:
</ResponseField>

<ResponseField name="data.cancelled" type="boolean" required>
  Whether a pending call was found and cancelled
</ResponseField>

<ResponseField name="data.phoneNumber" type="string" required>
  The normalized phone number
</ResponseField>

<ResponseField name="data.callQueueId" type="string">
  The ID of the cancelled queue item (only present when `cancelled` is `true`)
</ResponseField>

<ResponseField name="data.previousStatus" type="string">
  The queue item's status before cancellation (only present when `cancelled` is `true`)
</ResponseField>

<ResponseField name="data.status" type="string">
  The queue item's new status, always `"CANCELLED"` (only present when `cancelled` is `true`)
</ResponseField>

<ResponseField name="data.batchId" type="string">
  The batch ID the call belonged to, if it was part of a batch (only present when `cancelled` is `true`)
</ResponseField>

<Accordion title="Example Response (call cancelled)">
  ```json theme={null}
  {
    "success": true,
    "data": {
      "callQueueId": "cq_abc123",
      "phoneNumber": "966501234567",
      "previousStatus": "PENDING",
      "status": "CANCELLED",
      "batchId": "batch_xyz789",
      "cancelled": true
    }
  }
  ```
</Accordion>

<Accordion title="Example Response (no pending call found)">
  ```json theme={null}
  {
    "success": true,
    "message": "No pending call found for this phone number",
    "data": {
      "phoneNumber": "966501234567",
      "cancelled": false
    }
  }
  ```
</Accordion>

## Error Handling

<ResponseField name="error" type="string">
  Error message if the request fails
</ResponseField>

<Warning>
  Only calls with status `PENDING` in a batch with status `PENDING`, `SCHEDULED`, `QUEUED`, `ONGOING`, or `PAUSED` are cancellable. Calls that have already started, completed, or failed cannot be cancelled.
</Warning>

<Accordion title="Example Error Responses">
  ```json theme={null}
  {
    "error": "Invalid phone number format"
  }
  ```

  ```json theme={null}
  {
    "error": "Agent not found or does not belong to your company"
  }
  ```

  ```json theme={null}
  {
    "error": "API key missing company information"
  }
  ```
</Accordion>

<RequestExample>
  ```bash cURL theme={null}
  curl -X POST "https://app.sawt.sa/api/v1/calls/queue/cancel/966501234567" \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer your-api-key" \
    -d '{
      "agentId": "e63355c6-cf51-40f3-b006-b615d9ab762d"
    }'
  ```

  ```javascript Node.js theme={null}
  const axios = require("axios");

  const cancelQueuedCall = async (phoneNumber) => {
    try {
      const response = await axios.post(
        `https://app.sawt.sa/api/v1/calls/queue/cancel/${phoneNumber}`,
        {
          agentId: "e63355c6-cf51-40f3-b006-b615d9ab762d",
        },
        {
          headers: {
            Authorization: "Bearer your-api-key",
            "Content-Type": "application/json",
          },
        }
      );

      console.log(response.data);
      return response.data;
    } catch (error) {
      console.error(error);
    }
  };

  cancelQueuedCall("966501234567");
  ```

  ```python Python theme={null}
  import requests

  def cancel_queued_call(phone_number):
      url = f"https://app.sawt.sa/api/v1/calls/queue/cancel/{phone_number}"

      headers = {
          "Authorization": "Bearer your-api-key",
          "Content-Type": "application/json"
      }

      data = {
          "agentId": "e63355c6-cf51-40f3-b006-b615d9ab762d"
      }

      try:
          response = requests.post(url, headers=headers, json=data)
          response.raise_for_status()
          return response.json()
      except requests.exceptions.RequestException as e:
          print(f"Error: {e}")
          return None

  result = cancel_queued_call("966501234567")
  print(result)
  ```
</RequestExample>