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 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.

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.

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.

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 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.