Create a voice call with the API

Use POST /v1/voice/calls to call a phone number and start a published sequence when the recipient answers. The request places a real call; normal calling charges apply.

Before you start

Prepare these resources in the same workspace:

An enabled, unarchived sequence with an active publication.
Its sequence ID and the Voice call entry ID. Open the sequence's API connection guidance to copy the request for that entry.
An API key with both voice_management:write and voice:write permissions.
A calling number the workspace may present, such as an owned or verified caller ID, and an enabled destination country.
A recipient you control for the first call.

Create Call selects the active publication in production mode. For a saved-draft test, use the dashboard's Place a call controls. Inline definitions, historical version selection, and draft/test selectors are not accepted by Create Call.

Send the request

Set BIRD_API_KEY to your key and BIRD_API_URL to its regional base URL, such as https://eu1.platform.bird.com for an eu1 key.

Save the request as call.json, replacing the example numbers, sequence ID, and entry ID with your values:

Exemple de code

{
  "from": "+12025550100",
  "to": "+12025550101",
  "sequence": {
    "id": "YOUR_SEQUENCE_ID",
    "entry_node_id": "YOUR_ENTRY_NODE_ID",
    "trigger_data": {}
  }
}

trigger_data is a required object matching the entry's data schema. Use {} when the entry accepts empty data, or supply its declared fields. The Create Call reference documents request limits and the optional ringing timeout.

Choose a new CALL_IDEMPOTENCY_KEY for this intended call and retain it with the request file. Send:

Exemple de code

curl --request POST "$BIRD_API_URL/v1/voice/calls" \
  --header "Authorization: Bearer $BIRD_API_KEY" \
  --header 'Content-Type: application/json' \
  --header "Idempotency-Key: $CALL_IDEMPOTENCY_KEY" \
  --data-binary @call.json

A 202 Accepted response confirms admission. The sequence begins after the recipient answers. Publishing a newer version after acceptance does not change this call's selected definition or entry data.

Read the acceptance result

Retain the response's id, initial_leg_id, and sequence.run_id for correlation. The top-level id identifies the call across its legs; initial_leg_id identifies its first leg.

The response is an immutable acceptance snapshot. Its started_at and ended_at are null, observation booleans are false, and parties is empty. These fields describe acceptance, so they do not become a live status report when you replay the request.

Open the sequence's Runs to inspect progress. Once a leg record exists, use GET /v1/voice/legs/{leg_id} with initial_leg_id, or inspect the call log. Reading legs requires voice:read permission.

Acceptance does not guarantee dialing, an answer, or a readable call record. A call that fails before registration may appear in run history without a leg record. An answered call also does not establish that the sequence completed its intended business task.

Handle errors and retries

For a lost response or retryable server error, retry with the same key and the exact original request bytes. Keep using --data-binary @call.json; reformatting the JSON changes those bytes.

An identical replay within three hours returns the original acceptance and Idempotency-Replay: true. Changed input with that key returns 409. Authorization and calling-number permission are checked again on replay. After the replay window, the key can admit a new call, so reconcile the original result before resubmitting.

Symptom	What to check
400 or 422	Read the error's field details. Check the required idempotency key, number format, calling-number eligibility and ownership, sequence and entry IDs, explicit data object, and request limits.
401 or 403	Check the API key, both required write permissions, and workspace access.
404	Check the sequence belongs to the key's workspace and that call creation is available on the regional service.
409	Check for a changed-body retry or an unavailable active production sequence. Publish or resume as needed before beginning a new call.
429	Respect the response's retry guidance and retain the original key for the same call attempt.
Accepted, then failed	Inspect the run and any leg record for destination, limits, balance, or runtime failures before deciding to place another call.

Next steps

Ressources associées

Poursuivez avec la documentation, les guides et les exemples sur ce sujet. Les ressources sont en anglais.

Guide d'implémentationVoice sequences