# Create a call

`POST /v1/voice/calls`

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

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.

Send an `Idempotency-Key` header with a new key for each intended call.
For the curl example, export `IDEMPOTENCY_KEY` once before the first
attempt and keep the same value when retrying that 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.

## Code samples

**TypeScript**

```ts
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);
```

Examples: [TypeScript](/docs/api/reference/create-voice-call.ts.md) · [Python](/docs/api/reference/create-voice-call.py.md) · [Go](/docs/api/reference/create-voice-call.go.md) · [PHP](/docs/api/reference/create-voice-call.php.md) · [cURL](/docs/api/reference/create-voice-call.curl.md)

## Example response `202`

```json
{
  "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"
  }
}
```

## Request body

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

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

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