# `bird voice verified-numbers create`

## Usage

```bash
bird voice verified-numbers create [flags]
```

## Description

Create a verified number

Register a phone number as an outbound caller ID for the workspace. This places a verification call to the number that reads out a code, so register only a number the user controls. Returns the verified number in the "pending" state; submit the code with `bird voice verified-numbers verify`. A 412 means the organization's identity verification is incomplete, which is completed in the dashboard, or that an eligibility review or denial needs support. A 503 means the eligibility assessment is still pending; retry later.

Build the request from flags, a JSON VoiceVerifiedNumberCreate 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 verified-numbers create --example

# the body it prints:
```

```json
{
  "phone_number": "+14155551234"
}
```

## Options

#### 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` | Deduplication key; a retry with the same key won't act twice |

#### Options

| Name                | Description                                                                                                                                                                                                                                                                                               |
| ------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `--phone-number`    | The phone number to register as an outbound caller ID, in E.164 format (a leading + followed by the country code and national number). Must be unique within the workspace. Creating the verified number starts verification: a verification call is placed to this number. (required; or in --body-file) |
| `--name`            | Your label for this verified number, to tell several registered numbers apart. Omit it to register the number without one and add it later. It is yours to choose and appears nowhere on a call, so it never affects what the person you are calling sees.                                                |
| `--response-schema` | Print the fields this command returns, then exit                                                                                                                                                                                                                                                          |

## Related

| Name                                                                                      | Description              |
| ----------------------------------------------------------------------------------------- | ------------------------ |
| [`bird voice verified-numbers delete`](/docs/cli/reference/voice-verified-numbers-delete) | Delete a verified number |
| [`bird voice verified-numbers get`](/docs/cli/reference/voice-verified-numbers-get)       | Get a verified number    |
| [`bird voice verified-numbers list`](/docs/cli/reference/voice-verified-numbers-list)     | List verified numbers    |
| [`bird voice verified-numbers update`](/docs/cli/reference/voice-verified-numbers-update) | Update a verified number |
| [`bird voice verified-numbers verify`](/docs/cli/reference/voice-verified-numbers-verify) | Verify number ownership  |

## 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)