# `bird voice calls create`

## Usage

```bash
bird voice calls create [flags]
```

## Description

Create a call

Preview: run bird voice --help to discover installed commands and bird update --check for newer releases. Installation: https://bird.com/docs/cli. If calls create is absent, use the HTTP API or SDKs. Places a real outbound call after browser confirmation and starts the active published sequence after the recipient answers. Requires voice\_management:write and voice:write. Normal calling charges apply. Reuse the idempotency key and the same input for retries. Confirmation expires after 90 minutes; a missing result does not prove the call never ran. Acceptance does not prove a connected call.

Build the request from flags, a JSON CreateVoiceCallRequest body via --body-file ("-" reads
stdin), or both — a flag overrides the matching body field. Run --example to
print a ready-to-edit body, or --dry-run to print the resolved request without
sending it.

## Examples

```bash
# print the body shape (no credentials needed)
bird voice calls create --example

# the body it prints:
```

```json
{
  "from": "+12025550100",
  "sequence": {
    "entry_node_id": "start",
    "id": "vsq_01krdgeqcxet5s7t44vh8rt9mg",
    "trigger_data": {}
  },
  "to": "+12025550101"
}
```

```bash
# prepare a call for browser confirmation
bird voice calls create --body-file call.json --idempotency-key "${IDEMPOTENCY_KEY:?Set a fresh key for a new call; reuse it for retries}"

# inspect the same request without creating a confirmation
bird voice calls create --body-file call.json --idempotency-key "${IDEMPOTENCY_KEY:?Set a fresh key for a new call; reuse it for retries}" --dry-run
```

## Options

#### Call

| Name                            | Description                                                                              |
| ------------------------------- | ---------------------------------------------------------------------------------------- |
| `--from`                        | Permitted caller number in E.164 format (required; or in --body-file)                    |
| `--to`                          | Recipient number in E.164 format (required; or in --body-file)                           |
| `--sequence-id`                 | Published voice sequence to run (vsq\_ prefix) (required; or in --body-file)             |
| `--entry-node-id`               | Voice call entry node in the published sequence (required; or in --body-file)            |
| `--trigger-data`                | Entry data as a JSON object; use {} when no data is needed (required; or in --body-file) |
| `--ringing-timeout-seconds <n>` | Ringing timeout in seconds, from 5 to 120 (default 30)                                   |

#### Request

| Name                | Description                                                                                                |
| ------------------- | ---------------------------------------------------------------------------------------------------------- |
| `--body-file`       | Read the JSON request body from this file; "-" reads stdin                                                 |
| `--example`         | Print a complete example request body, then exit                                                           |
| `--dry-run`         | Print the resolved request without sending it, then exit                                                   |
| `--idempotency-key` | Stable key for this intended call; reuse with identical input to retrieve the same confirmation (required) |

#### Options

| Name                | Description                                             |
| ------------------- | ------------------------------------------------------- |
| `--response-schema` | Print the fields this command returns, then exit        |
| `--confirmation-id` | Wait for an existing confirmation of this exact request |

## Related resources

- [Should I use a Bird SDK or call the API directly?](/explained/platform/should-i-use-an-sdk-or-call-the-api-directly) (answer)
- [Build your first integration](/learn/paths/integration) (course)
- [Send your first email](/docs/get-started/send-your-first-email) (docs)

[Get an implementation brief](/learn/workspace?topic=api-basics)