Documentation
Sign inGet Started
Get started
Guides
API Reference
SDKs
CLI
Knowledge Base
Changelog

Create a call

POST
/v1/voice/calls
const call = await bird.voice.calls.create({
  from: "+12025550100",
  to: "+12025550101",
  sequence: {
    id: "vsq_01krdgeqcxet5s7t44vh8rt9mg",
    entry_node_id: "start",
    trigger_data: {},
  },
});
console.log(call.id, call.initial_leg_id, call.sequence?.run_id);
Response202
{
  "id": "vcs_01krdgeqcxet5s7t44vh8rt9mg",
  "workspace_id": "ws_01krdgeqcxet5s7t44vh8rt9mg",
  "initial_leg_id": "vcl_01krdgeqcxet5s7t44vh8rt9mg",
  "direction": "outbound",
  "started_at": null,
  "ended_at": null,
  "live": false,
  "has_recording": false,
  "has_transcript": false,
  "parties": [],
  "sequence": {
    "id": "vsq_01krdgeqcxet5s7t44vh8rt9mg",
    "run_id": "vsr_01krdgeqcxet5s7t44vh8rt9mg"
  }
}
Accepts a real outbound call using the active publication of a voice sequence. The sequence starts at the selected entry node after the recipient answers. 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. Create and publish the sequence in the dashboard before calling this endpoint; inline definitions and draft/test selectors are not accepted. See the Create Call guide.
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, 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 20 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.
Request Payload
from
string
required
Calling number that this workspace is permitted to present.
to
string
required
Recipient number in canonical E.164 form.
ringing_timeout_seconds
integer
Maximum ringing time for the original dialing attempt, shared across routing candidates.
sequence
object
required
Show child parameters
sequence.id
string
required
Published voice sequence to run after the recipient answers.
sequence.entry_node_id
string
required
Voice call entry node to start.
sequence.trigger_data
object
required
Data matching the selected entry's configured schema, limited to 16 KiB before and after normalization. Use an empty object when the entry needs no data. Fields remain application data and cannot provide trusted call identity or routing authority.
Response Payload
id
string
required
Unique identifier for this call, shared by every leg that belongs to it.
workspace_id
string
required
initial_leg_id
string
required
The initial leg identity. For an accepted outbound call, this identity is reserved before the leg starts.
direction
string
required
Direction of the initial leg.
started_at
nullable string
required
When the initial leg started. null in the acceptance snapshot returned by call creation.
ended_at
nullable string
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 currently holds a lease. 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
array of object
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.
Show child attributes
parties.endpoint
nullable object
What kind of participant sat on this side of a leg, and the coordinate that kind carries: a telephone endpoint off the platform, a SIP or WebRTC endpoint, Bird answering, or the platform placing a leg onward. It does not name a person. null on an observation this API could not read. The entry stays, because the session counted it when it deduplicated, and dropping it here would report fewer participants than were observed.
Show child attributes
parties.endpoint.type
string
required
What kind of participant sat on this side of a leg. It selects which payload below is present, and most kinds carry none because the party's address is already their coordinate.
Possible values (may grow over time): pstn, sip, voicemail, bridge_pstn, bridge_sip, webhook
parties.endpoint.sip
object
The registered contact of a sip endpoint. Absent when the observation recorded none, and on every other kind of endpoint.
Show child attributes
parties.endpoint.sip.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.
parties.endpoint.bridge_pstn
object
Where the platform placed the leg onward, on a bridge_pstn endpoint. Absent on every other kind of endpoint.
Show child attributes
parties.endpoint.bridge_pstn.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.
parties.endpoint.bridge_pstn.forward_as
string
required
Which number the forwarded leg presented to the far end.
Possible values: dialed_number, calling_number
parties.endpoint.bridge_sip
object
The trunk the platform delivered the leg onward to, on a bridge_sip endpoint. Absent on every other kind of endpoint.
Show child attributes
parties.endpoint.bridge_sip.trunk_id
string
required
The workspace trunk the leg was delivered onward to. It is distinct from the party's own trunk_id, which is the trunk this side itself sat behind.
parties.address
nullable string
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.
parties.trunk_id
nullable string
The workspace trunk on this side of the leg. null when this side sat behind no trunk.
sequence
object
Sequence and run accepted for this outbound call. Present in the immutable acceptance snapshot returned by call creation. Current call detail and list reads omit this property, including for calls created from a sequence.
Show child attributes
sequence.id
string
required
Voice sequence selected for this call.
sequence.run_id
string
required
Run created from the sequence's frozen publication.

Related resources

Continue with the documentation, guides and examples for this topic. Resources are in English.

Implementation guideVoice sequences