# Create a voice call with the API

Use [`POST /v1/voice/calls`](/docs/api/reference/create-voice-call) 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](/docs/guides/voice/sequences/publishing).
- 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](/docs/api/authentication) with both `voice_management:write` and `voice:write` permissions.
- A calling number the workspace may present, such as an owned or verified [caller ID](/docs/guides/voice/caller-ids), and an enabled [destination country](/docs/guides/voice/destinations).
- 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](/docs/guides/voice/sequences/testing) 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](/docs/api/regions), 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:

```json
{
  "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](/docs/api/reference/create-voice-call) 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:

```bash
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**](/docs/guides/voice/sequences/runs) to inspect progress. Once a leg record exists, use [`GET /v1/voice/legs/{leg_id}`](/docs/api/reference/get-voice-leg) with `initial_leg_id`, or inspect the [call log](/docs/guides/voice/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

- [Create Call API reference](/docs/api/reference/create-voice-call).
- [Define sequence entry data](/docs/guides/voice/sequences/data).
- [Inspect sequence runs](/docs/guides/voice/sequences/runs).
- [Receive call events](/docs/guides/voice/events).

## Related resources

- [Voice sequences](/docs/guides/voice/sequence-builder) (docs)