# Managing your phone numbers

Once a number is allocated to your workspace, the numbers API lets you list what you hold, find one number by any of its handles, label it with a name and your own reference, and release it when you are done. Reading needs an API key with the `numbers` scope at read level; changing or releasing a number needs write level.

The [**Numbers**](https://bird.com/dashboard/w/numbers) page in the dashboard shows the same numbers.

## List every number you hold

[`GET /v1/numbers`](/docs/api/reference/list-workspace-numbers) returns the numbers currently allocated to your workspace, newest first, dedicated and shared alike. Each page holds 25 numbers unless you ask for up to 100 with `limit`.

The list is paged by cursor. Pass a page's `next_cursor` back as `starting_after` to read the next page, and stop when `next_cursor` is `null`. The SDKs follow the cursor for you. The examples below narrow the list to `country_code: "GB"`; leave the filter out to walk every number you hold:

**TypeScript**

```typescript
for await (const allocated of bird.numbers.list({ country_code: "GB" })) {
  // kind distinguishes a number you bought from one Bird manages.
  console.log(allocated.number, allocated.kind, allocated.status);
}
```

Examples: [TypeScript](/docs/guides/numbers/managing-numbers.ts.md) · [Python](/docs/guides/numbers/managing-numbers.py.md) · [Go](/docs/guides/numbers/managing-numbers.go.md) · [PHP](/docs/guides/numbers/managing-numbers.php.md) · [MCP](/docs/guides/numbers/managing-numbers.mcp.md) · [cURL](/docs/guides/numbers/managing-numbers.curl.md)

Use the regional host that matches your key's `bk_{region}_` prefix: `https://us1.platform.bird.com` or `https://eu1.platform.bird.com`.

The list carries no total. To count your numbers, walk the pages to the end and count the entries. Passing `include_total` is refused with `422` and [`E01029`](/docs/api/errors/E01029).

Each entry carries its `status` and `ownership`. Where a country asks for no ownership paperwork, `ownership` is `null`. The [Numbers overview](/docs/guides/numbers/overview#the-status-of-an-allocated-number) explains what each status means.

## Find a number in your list

The list filters combine, so a country or capability filter still applies alongside the others.

`number` looks up one number however your records spell it. `+31612345678` and `0031612345678` resolve to the same number. A national spelling such as `0612345678` resolves only when `country_code` names the country:

```bash
curl "https://us1.platform.bird.com/v1/numbers?number=0612345678&country_code=NL" \
  -H "Authorization: Bearer bk_us1_..."
```

When you pass a full number, or a national spelling with its `country_code`, and no other filter, an empty `data` array means the number is not allocated to your workspace, which includes a number you have released. A national spelling without `country_code`, such as `0612345678` on its own, also returns an empty list, so it does not prove the number is not yours.

`search` matches part of the number, its name, or its reference, ignoring case. `reference` returns the numbers with exactly that reference, matching case:

```bash
curl "https://us1.platform.bird.com/v1/numbers?reference=STORE-042" \
  -H "Authorization: Bearer bk_us1_..."
```

`prefix` returns numbers that start with the digits you give, and what those digits mean depends on `country_code`:

- With `country_code`, the digits are national ones, matched right after the dial code. `prefix=6&country_code=NL` returns Dutch numbers that start `+31 6`.
- Without `country_code`, the digits are matched from the start of the full number. `prefix=6` on its own returns numbers whose dial code starts with 6, such as Australian `+61` numbers, so it finds none of your Dutch mobiles. It also matches short codes that start with those digits.

## Name a number and set your reference

A number carries two labels of your own. `name` tells your numbers apart, such as `Support line`. `reference` holds an identifier from your own records, such as a customer or store id, and it need not be unique. Both apply to dedicated and shared numbers and are up to 100 characters.

Set them with [`PATCH /v1/numbers/{number_id}`](/docs/api/reference/update-workspace-number). A field you omit keeps its current value, and a field you send as `null` is cleared. Leading and trailing whitespace is removed.

**TypeScript**

```typescript
const allocated = await bird.numbers.update("nda_01krdgeqcxet5s7t44vh8rt9mg", {
  name: "Support line",
  reference: "STORE-042",
});
console.log(allocated.name, allocated.reference);
```

Examples: [TypeScript](/docs/guides/numbers/managing-numbers.ts.md) · [Python](/docs/guides/numbers/managing-numbers.py.md) · [Go](/docs/guides/numbers/managing-numbers.go.md) · [PHP](/docs/guides/numbers/managing-numbers.php.md) · [MCP](/docs/guides/numbers/managing-numbers.mcp.md) · [cURL](/docs/guides/numbers/managing-numbers.curl.md)

The response is `200` with the updated number. To clear the reference and keep the name, send the reference as `null` and leave the name out:

```bash
curl -X PATCH "https://us1.platform.bird.com/v1/numbers/nda_01krdgeqcxet5s7t44vh8rt9mg" \
  -H "Authorization: Bearer bk_us1_..." \
  -H "Content-Type: application/json" \
  -d '{"reference": null}'
```

To set the reference when you buy the number, pass `reference` on [`POST /v1/numbers/orders`](/docs/api/reference/create-numbers-order). An order that has to wait on a carrier keeps the reference until the number is allocated, and the number carries it from then on.

## Find the voice record that routes a number

A number that carries voice has two identifiers. The `id` on `GET /v1/numbers` starts with `nda_` for a dedicated number and `nal_` for a shared one, and the numbers operations take it. The voice operations, including the one that sets where incoming calls go, take the number's voice record, whose `id` starts with `vnu_`. Passing an `nda_` id to a voice operation is refused with `422`.

To get from one to the other, search the voice numbers by the phone number. This needs the `voice_management` scope at read level:

```bash
curl "https://us1.platform.bird.com/v1/voice/numbers?search=%2B31612345678" \
  -H "Authorization: Bearer bk_us1_..."
```

The entry's `id` is the `vnu_` identifier, and its `provider.number_id` is the `nda_` identifier of the same number. [Receiving calls](/docs/guides/voice/receiving-calls) shows how to route the number from there.

The voice record has a `name` of its own. Naming a number with `PATCH /v1/numbers/{number_id}` leaves the voice record's name unchanged, and the reverse holds too.

## Release a number

Releasing a dedicated number with [`DELETE /v1/numbers/{number_id}`](/docs/api/reference/release-workspace-number) takes effect immediately. [Buy and release a number](/docs/guides/numbers/buying-numbers#release-a-number) shows the call in each SDK.

Send a release with an `Idempotency-Key` so a retry is safe: the same key replays the `204` with an `Idempotency-Replay: true` header, while a new request for a number already released answers `404` with [`E01008`](/docs/api/errors/E01008). [Idempotency](/docs/guides/idempotency) explains how long a key is kept.

After the release:

- The number stops working for you, and its subscription ends with the period you already paid for instead of renewing.
- `GET /v1/numbers/{number_id}` and the number's voice record answer `404`, and the number leaves `GET /v1/numbers`.
- The number's order stays in [`GET /v1/numbers/orders`](/docs/api/reference/list-numbers-orders), and its `number_id` now answers `404`.
- The number goes into a 30-day cooldown before it can return to sale, so you cannot buy the same number back straight away.

## Next steps

- [Receiving calls](/docs/guides/voice/receiving-calls) routes a number to a SIP trunk, a forward, or a sequence.
- [Buy and release a number](/docs/guides/numbers/buying-numbers) walks the purchase over the API.
- [Numbers API reference](/docs/api/reference/list-workspace-numbers) documents every operation and field.

## Related resources

- [What is a virtual phone number (VMN)?](/explained/numbers/what-is-a-virtual-phone-number) (answer)
- [SMS numbers](/sms-api/features/numbers) (product)
- [Number types](/docs/guides/numbers/number-types) (docs)

[Get an implementation brief](/learn/workspace?topic=phone-numbers)