---
title: "Cancel Call"
method: DELETE
path: "/calls/{id}"
tags: ["Calls"]
---

# Cancel Call

`DELETE /calls/{id}`

## Request

- Base URL: `https://api.pinnacle.sh`
- URL: `https://api.pinnacle.sh/calls/{id}`
- Auth: API key in header `PINNACLE-API-KEY`

End a live call. Terminal calls are returned unchanged.

## Path parameters

- `id` string, required

## Response `200`

Canceled call.

- Call
  - `id` string, required
  - `state` 'INITIATED' | 'RINGING' | 'ANSWERED' | 'BRIDGED' | 'ENDED' | 'FAILED' | 'NO_ANSWER' | 'BUSY' | 'CANCELED', required: Current voice call lifecycle state. This field is named `state` on Call objects and `status` on `CALL.STATUS` webhook payloads. - `INITIATED`: Pinnacle accepted the call request and is setting up the call with the voice provider. - `RINGING`: The call is ringing and has not been answered yet. - `ANSWERED`: The call has been answered and is active. - `BRIDGED`: The call is connected to another call leg, such as after a transfer or bridge command. - `ENDED`: The call ended normally. - `FAILED`: The call could not be established or could not continue because of a provider or system failure. - `NO_ANSWER`: The call rang until timeout without being answered. - `BUSY`: The destination was busy. - `CANCELED`: The call was canceled before normal completion.
  - `direction` 'INBOUND' | 'OUTBOUND', required: Direction of the call relative to your Pinnacle team. - `INBOUND`: The call originated from an external caller and was received by one of your Pinnacle voice-enabled phone numbers. - `OUTBOUND`: The call was created from Pinnacle and dialed out from one of your voice-enabled phone numbers.
  - `to` string, required
  - `from` string, required
  - `created_at` string, date-time, required
  - `started_at` string, date-time, nullable, required
  - `answered_at` string, date-time, nullable, required
  - `ended_at` string, date-time, nullable, required
  - `metadata` object, required
  - `record` boolean, required: Whether recording was requested when this call was created. This is intent, not progress. `recording_state` says what happened to the audio; `record` says whether any was ever asked for. A call with `record: true` and `recording_state: null` after it has ended means a recording was expected but never produced.
  - `recording_state` 'PENDING' | 'READY' | 'FAILED' | 'DELETED', required: Recording processing state for a call. - `PENDING`: Audio was captured and is still being finalized. Download returns `425` until processing completes. - `READY`: The recording is finalized and can be downloaded with a signed URL. - `FAILED`: Recording finalization failed. Download returns `422`. - `DELETED`: The recording was deleted. Download returns `410`.
  - `hangup_cause` string, nullable, required
  - `conference_id` string, nullable: The conference this call is in, or was most recently in; `null` if never. Returned by `GET /calls/{id}`.

## Other responses

- `401`: The request lacks valid authentication credentials or the provided credentials are invalid. <br> Ensure you're including a valid API key in the request headers and that your account has the necessary permissions to access this endpoint.
- `404`: The requested resource could not be found. <br> This may occur if the identifier is incorrect, the resource has been deleted, or you don't have permission to access it.
- `500`: An unexpected error occurred on Pinnacle's servers while processing your request. <br> If this error persists, please contact support with the request details.
- `502`: One of Pinnacle's providers failed. Please try again later.
- `503`: This service is temporarily unavailable. Please try again later or contact support if the issue continues.

---

[API](https://skmtc.dev/pinnacle/apis/pinnacle-2.md) - [All operations](https://skmtc.dev/pinnacle/apis/pinnacle-2/llms.txt) - [OpenAPI document](https://skmtc.dev/pinnacle/apis/pinnacle-2/revisions/45416dadab79?raw)