# Numbers overview

A phone number is what your messages and calls come from. Bird sells numbers in the countries it covers, and a number your workspace holds can carry SMS, MMS, or voice depending on what the number supports. The [**Numbers**](https://bird.com/dashboard/w/numbers) page in the dashboard shows the numbers you hold, and the same lifecycle is available over the API: search what is on sale, order one, read what you hold, and release what you no longer need.

## Dedicated and shared numbers

Every number you hold has a `kind`, and it decides what you can do with the number.

A `dedicated` number belongs to your workspace alone. You bought it, you are billed a monthly charge for it, and you can release it when you are done. This is what ordering a number gives you.

A `shared` number is a short code Bird manages across several workspaces. You are granted the use of it rather than buying it, so there is no monthly charge of your own and you cannot release it. Attempting to release one fails with [`E14002`](/docs/api/errors/E14002).

## What a number can carry

Two fields describe what a number is, and they answer different questions.

`number_type` is the number's physical kind: `mobile`, `local`, `national`, `toll_free`, or a short code. It decides how the number behaves on the network and, in several countries, what paperwork it needs.

`capabilities` is what the number can actually do: `sms`, `mms`, `voice`, or a combination. A number that lists `voice` can carry calls; one that does not, cannot. Filter a search by capability when you need a specific one, and check the field before you build on a number you already hold.

Holding a number is not always enough to send from it. Some destination countries also require an approved registration for the sender, which is separate from owning the number.

## The status of a number you hold

`status` says whether a number can carry traffic.

`active` means you hold the number and it is usable.

`pending_compliance` means you hold the number and are billed for it, but a country asks for ownership paperwork that has not been accepted yet. The `ownership` field says what is still outstanding and which call advances it. Most numbers never enter this state, because most countries ask for nothing: their `ownership` is `null`.

`released` means you no longer hold the number.

## Ordering is asynchronous

Ordering a number creates an order, and the order is the thing you track. Most complete inside the request and hand back the number immediately. One that has to wait on a carrier comes back still running, and you poll it until it reaches `completed` or `failed`.

This matters for two reasons. A number is only yours once its order is `completed`, so nothing should assume the number exists before then. And a setup fee that has already been charged is not refunded when an order fails, which is why the search and the order are separate calls: the search tells you what is available before you commit to buying it.

## Next steps

- [Buy and release a number](/docs/guides/numbers/buying-numbers) walks the full lifecycle over the API.
- [Numbers API reference](/docs/api/reference/list-available-numbers) documents every operation and field.
- [Idempotency](/docs/guides/idempotency) explains how to make a retried order safe.