Calls

Create Call

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.

post/calls

Request

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

Headers

Idempotency-Keystring

Client-generated key making this request safe to retry. Use a fresh value per distinct call (a UUID is fine) and reuse it only when retrying that same call.

Request body

tostring required

Destination phone number in E.164 format.

fromstring required

Voice-enabled phone number owned by your team.

recordboolean

Start recording as soon as the call stream connects.

metadataCallMetadata

String metadata carried on future call events. Maximum serialized size is 2 KB.

Response

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

idstring 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.
tostring required
fromstring required
created_atstring date-time required
started_atstring date-time nullable required
answered_atstring date-time nullable required
ended_atstring date-time nullable required
metadataobject 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_causestring nullable required
recordboolean required

Echoes the requested create-time recording option. This field is only returned by POST /calls.

Changes

No recorded changes to this operation across all 1 revision of this API.