# `bird numbers update`

## Usage

```bash
bird numbers update <number-id> [flags]
```

## Description

Update an allocated number

Set the name or your own reference on an allocated number. Omit a field to preserve it, or send null to clear it. Applies to dedicated and shared numbers.

Build the request from flags, a JSON NumberUpdate 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 numbers update --example

# the body it prints:
```

```json
{
  "name": "Support line",
  "reference": "STORE-042"
}
```

## 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                                                                                                                                                                  |
| ------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `--name`            | A name for this number in your workspace, such as Support line. Send null to clear it, or omit it to keep the current name.                                                  |
| `--reference`       | Your own reference for this number, such as an identifier from your records. References need not be unique. Send null to clear it, or omit it to keep the current reference. |
| `--response-schema` | Print the fields this command returns, then exit                                                                                                                             |

## Related

| Name                                                          | Description                 |
| ------------------------------------------------------------- | --------------------------- |
| [`bird numbers get`](/docs/cli/reference/numbers-get)         | Get an allocated number     |
| [`bird numbers list`](/docs/cli/reference/numbers-list)       | List your allocated numbers |
| [`bird numbers release`](/docs/cli/reference/numbers-release) | Release a dedicated number  |

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