voice-calls

Create a call

Accepts a real outbound call that runs a voice sequence after the recipient answers, starting at the selected entry node. Supply exactly one of sequence.id, to run the active publication of a saved sequence, or sequence.definition, to run a complete definition once without saving it. Production availability rules and normal calling charges apply. Requires both voice management write and voice calling write permissions and a permitted calling number. Browser users and API keys are supported. Draft and test selectors are not accepted. See the Create Call guide.

An inline definition must pass the same checks as publishing a sequence; the first blocking problem returns 422 with its location under /sequence/definition. Its run executes at most 16 commands, including gather prompts; a call that needs a 17th ends with the call_limit trace error instead of running it. The accepted call's sequence.id is null, because its run belongs to no saved sequence.

Supply sequence trigger data as an explicit object matching the selected entry's configured data schema, or an empty object when no data is needed. The active publication or inline definition, entry node, and trigger data are frozen when the call is accepted. The response contains reserved call and initial-leg IDs. Its null started_at, false live, and empty parties describe the acceptance snapshot. Acceptance does not guarantee that dialing starts or that call and leg reads become available. A call that fails or is canceled before registration might never appear in those reads. Read progress in the sequence's Runs tab in the dashboard. Once the initial leg is registered, use its initial_leg_id with GET /v1/voice/legs/{leg_id} to inspect the telephone outcome; that read requires voice read permission.

Idempotency is optional. Without an Idempotency-Key header, each request accepts a new call attempt. To protect retries, supply a key on the first attempt and reuse it for the same intended call. Requests are limited to 128 KiB. The same idempotency key and exact request bytes replay the original acceptance snapshot for three hours. Changed requests return 409. Authorization and calling-number permission are checked on every request, including replays. Replays include the Idempotency-Replay header with value true.

post/v1/voice/calls

Request

  • Base URL: https://us1.platform.bird.com
  • URL: https://us1.platform.bird.com/v1/voice/calls
  • Auth: one of:
    • HTTP bearer
    • API key in cookie bird_session

Headers

Idempotency-Keystring

Client-supplied key. On operations supporting request deduplication, a retained response is replayed for duplicate requests with the same key within the idempotency window (3 hours by default). This protection requires a workspace, organization, or staff-account scope. User-only and unscoped unauthenticated operations, streams, and operations with a separate replay contract do not use this response replay.

On a supported operation, if idempotency protection is unavailable before execution, the API returns 503 IdempotencyUnavailable (E01033) without executing this attempt. Retry with backoff using the same key and request. An operation that takes effect before its response is retained can still execute again on retry.

Two distinct 409 errors signal misuse:

  • request_in_progress (E01004): The same key is currently being processed by a concurrent request. Wait briefly and retry. The lock expires within 30 seconds.
  • idempotency_key_reuse (E01005): The same key has already completed against a different request body or method. Generate a new key.

Recommended key format is <event-type>/<entity-id> (for example welcome-user/usr_abc123).

X-Workspace-Idstring

Workspace context for the request. Required for dashboard authentication and master keys. Workspace keys and access tokens already identify their workspace; send that workspace or omit the header. A different one is rejected.

X-Organization-Idstring

Organization context for the request. Required for dashboard authentication. An API key or access token carries its own organization, so send either that organization or no header at all; a different one is rejected.

Request body

fromstring required

Canonical E.164 phone number, with a leading plus sign and four to fifteen digits.

tostring required

Canonical E.164 phone number, with a leading plus sign and four to fifteen digits.

ringing_timeout_secondsinteger

Maximum ringing time for the original dialing attempt, shared across routing candidates.

sequenceCreateVoiceCallSequenceRequest required(unresolved $ref)

Response

Immutable acceptance snapshot for the call.

idstring required
workspace_idstring required
initial_leg_idstring required
direction'inbound' | 'outbound' required

Whether the call was placed from your side, by your PBX, the API, the browser or Bird dialing onward for you (outbound), or arrived from a remote party (inbound).

started_atstring date-time nullable required

When the initial leg started. null in the acceptance snapshot returned by call creation.

ended_atstring date-time nullable

When the call's last leg ended. null while any leg is still in progress. Recordings and transcripts can still arrive after this instant, so it does not mean the call is finished being written.

liveboolean required

Whether any leg in the call is still held live. A leg stays live until its end is recorded or, when no end is observed, until its liveness window expires, so this can remain true briefly after a disconnect. false covers the interval between a leg ending and its settlement being confirmed, and says nothing about whether transcription has finished.

has_recordingboolean required

Whether the call ever produced a recording. It stays true for the life of the call, so it records that a recording was made rather than promising one can still be fetched.

has_transcriptboolean required

Whether the call ever produced a transcript. A failed transcription attempt does not set it, and a later failure does not clear it.

Example response

{
  "id": "vcs_01krdgeqcxet5s7t44vh8rt9mg",
  "workspace_id": "ws_01krdgeqcxet5s7t44vh8rt9mg",
  "initial_leg_id": "vcl_01krdgeqcxet5s7t44vh8rt9mg",
  "direction": "outbound",
  "started_at": "2026-05-21T12:00:00Z",
  "parties": [
    {
      "endpoint": {
        "type": "pstn",
        "sip": {
          "contact": "sip:ua@203.0.113.7:5060"
        },
        "bridge_pstn": {
          "forward_to": "+31612345678",
          "forward_as": "dialed_number"
        },
        "bridge_sip": {
          "trunk_id": "spt_01krdgeqcxet5s7t44vh8rt9mg"
        }
      },
      "address": "+14155551234",
      "trunk_id": "spt_01krdgeqcxet5s7t44vh8rt9mg"
    }
  ],
  "sequence": {
    "id": "vsq_01krdgeqcxet5s7t44vh8rt9mg",
    "run_id": "vsr_01krdgeqcxet5s7t44vh8rt9mg"
  }
}

Changes

No recorded changes to this operation across all 2 revisions of this API.