---
title: "Create a call"
method: POST
path: "/v1/voice/calls"
tags: ["voice-calls"]
---

# Create a call

`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`

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](https://bird.com/docs/guides/voice/create-calls).

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.

## Headers

- `Idempotency-Key` string
- `X-Workspace-Id` string
- `X-Organization-Id` string

## Request body

- CreateVoiceCallRequest
  - `from` string, required: Canonical E.164 phone number, with a leading plus sign and four to fifteen digits.
  - `to` string, required: Canonical E.164 phone number, with a leading plus sign and four to fifteen digits.
  - `ringing_timeout_seconds` integer: Maximum ringing time for the original dialing attempt, shared across routing candidates.
  - `sequence` CreateVoiceCallSequenceRequest, required (unresolved $ref)

## Response `202`

Immutable acceptance snapshot for the call.

- VoiceCall: A call summary. Call reads report observed state. Call creation returns an immutable acceptance snapshot: `started_at` and `ended_at` are `null`, the boolean observation fields are `false`, and `parties` is empty. Replays return that same snapshot after the call progresses.
  - `id` string, required
  - `workspace_id` string, required
  - `initial_leg_id` string, 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_at` string, date-time, nullable, required: When the initial leg started. `null` in the acceptance snapshot returned by call creation.
  - `ended_at` string, 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.
  - `live` boolean, 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_recording` boolean, 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_transcript` boolean, required: Whether the call ever produced a transcript. A failed transcription attempt does not set it, and a later failure does not clear it.
  - `parties` VoiceParty[], required: The distinct participant observations the call's legs recorded, for display beside the call. The length is not a count of people and not a reconstruction of the leg graph.
    - `endpoint` VoicePartyEndpoint
      - `type` string, required: The technical participant observed on one side of a call. Additional endpoint types may appear in retained observations.
      - `sip` VoicePartySIPEndpoint
        - `contact` string, required: The address the user agent registered, as a `sip:` or `sips:` URI. It is where the endpoint asked to be reached, which is not always the address that was dialled.
      - `bridge_pstn` VoicePartyBridgePSTNEndpoint
        - `forward_to` string, required: The number the platform placed the leg onward to, in E.164. The party's own `address` is the number that was dialled, so the two together are one hop of the call.
        - `forward_as` 'dialed_number' | 'calling_number', required: Which of a forwarded call's two numbers it shows as the caller. `dialed_number` presents the Bird number the caller dialed. Whoever answers sees which of your numbers was called. Older configurations without a stored choice use this value. Carrier screening can still affect delivery. `calling_number` presents the caller's own number, so the phone rings as though they had dialed it directly and the call can be returned from the call log. Because the number is not one you own, some carriers (most often in the US and parts of Europe) mark such calls as unverified, replace the number, or screen them.
      - `bridge_sip` VoicePartyBridgeSIPEndpoint
        - `trunk_id` string, required
    - `address` string, nullable: This side's own address, in E.164 or as a `sip:` URI. `null` when the observation carried none, which does not say whether one was withheld, missing, or nonexistent.
    - `trunk_id` string
  - `sequence` VoiceCallSequence
    - `id` string, required
    - `run_id` string, required

## Other responses

- `400`: Bad request
- `401`: Authentication required
- `403`: Insufficient permissions
- `404`: Resource not found
- `409`: Resource conflict
- `422`: The request has invalid field values, violates a business rule, or carries a query parameter the endpoint does not declare. Field validation errors use `type: validation_error` and include the affected fields in `details`. Business-rule errors identify the failed rule in `type`.
- `429`: Rate limit exceeded
- `500`: Internal server error
- `503`: The service is temporarily unavailable. If `Retry-After` is present, wait for that delay before retrying; otherwise, retry with exponential backoff. Reuse the same idempotency key and request when retrying a mutation.

---

[API](https://skmtc.dev/messagebird/apis/bird-api.md) · [All operations](https://skmtc.dev/messagebird/apis/bird-api/llms.txt) · [OpenAPI document](https://skmtc.dev/messagebird/apis/bird-api/revisions/3e2a50466454?raw)