---
title: "Create Call"
method: POST
path: "/calls"
tags: ["Calls"]
---

# Create Call

`POST /calls`

## Request

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

Start an outbound voice call from a voice-enabled phone number owned by
your team.

**Retrying safely.** Send an `Idempotency-Key` header and the call is
placed at most once, however many times the request is repeated. This
matters more here than on most endpoints: a retry without one dials the
recipient a second time.

- Same key, same request: returns the original call with `200` instead
  of `201`, and no new call is placed.
- Same key, different request: `422`. The key is bound to the request
  it was first used with, so returning the unrelated original call
  would be worse than refusing.
- Same key while the first attempt is still in flight: `409`. Retry
  once it settles.

Keys are scoped to your team and expire after 24 hours. Two requests
count as the same when `to`, `from`, `record` and `metadata` match;
metadata key order is not significant.

## Headers

- `Idempotency-Key` string

## Request body

- CreateCallParams
  - `to` string, required: Destination phone number in E.164 format.
  - `from` string, required: Voice-enabled phone number owned by your team.
  - `record` boolean: Start recording as soon as the call stream connects.
  - `metadata` CallMetadata: String metadata carried on future call events. Maximum serialized size is 2 KB.

## Response `200`

Replay of an earlier request with the same `Idempotency-Key`. The
original call is returned and no new call was placed.

- CreatedCall
  - `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
  - `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
  - `record` boolean, required: Echoes the requested create-time recording option. This field is only returned by `POST /calls`.

## Other responses

- `400`: Validation failed. The payload has missing required fields and/or invalid types. <br> See https://zod.dev/error-formatting for more information.
- `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.
- `403`: Your subscription does not include access to this feature. <br> This occurs when attempting to use functionality that requires a higher subscription tier. Please upgrade your subscription to access this feature.
- `409`: A call for this `Idempotency-Key` is still being created. Retry once it settles rather than sending a new key, which would place a second call.
- `422`: This `Idempotency-Key` was already used for a different request. Use a fresh key for a different call.
- `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)