Skip to navigation
API ReferenceCallsCall Lifecycle

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.

Authentication

PINNACLE-API-KEYstring
API Key authentication via header

Headers

Idempotency-KeystringOptional<=255 characters

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

This endpoint expects an object.
tostringRequiredformat: "^\+[1-9]\d{1,14}$"
Destination phone number in E.164 format.
fromstringRequiredformat: "^\+[1-9]\d{1,14}$"

Voice-enabled phone number owned by your team.

recordbooleanOptional
Start recording as soon as the call stream connects.
metadatamap from strings to stringsOptional
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
stateenum

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.
directionenum

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.
Allowed values:
tostring
fromstring
created_atstringformat: "date-time"
started_atstring or nullformat: "date-time"
answered_atstring or nullformat: "date-time"
ended_atstring or nullformat: "date-time"
metadatamap from strings to strings
recording_stateenum or null

If no recording has been captured or enabled for the call, then null.

Allowed values:
hangup_causestring or null
recordboolean

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

Errors

400
Bad Request Error
401
Unauthorized Error
403
Forbidden Error
409
Conflict Error
422
Unprocessable Entity Error
500
Internal Server Error
502
Bad Gateway Error
503
Service Unavailable Error