Number types

A number's number_type is its physical kind on the phone network. It decides how the number behaves when a carrier routes to it, which registration a country asks for before you can send from it, and in several markets whether the number is on sale at all. Numbers overview covers the other fields on an allocated number, kind, capabilities and status. This page is how to choose between the types themselves.

Six values ship today. New types are added as coverage grows, so treat an unfamiliar value as a supported type rather than an error.

One rule holds across all of them: the type tells you what kind of number you have, and capabilities tells you what that particular number can actually do. A type's typical capabilities vary by country and by the carrier the number came from, so filter a search by the capability you need and read the field back on the number you were allocated. Never infer SMS or voice from the type alone.

A number drawn from the same ranges a mobile network gives to handsets. In the markets that have them, mobile numbers usually carry the broadest set of capabilities of any type, which makes one the number to reach for when a single number has to do several jobs: send and receive SMS, and take calls, under one identity your customer sees consistently.

Choose mobile for two-way conversational messaging, and wherever you would rather hold one number than reconcile several.

A number whose leading digits are an area code belonging to a city or a region. A local number reads as nearby to the person receiving the call, which is what it is for: a branch, a regional team, or a business whose customers expect to reach someone in their own area.

Local numbers are the type most likely to carry voice but not messaging, so capabilities matters more here than anywhere else.

A number on a country-wide prefix rather than a regional one. It gives every customer in the country the same number to call, so it suits a head office, a single support line, or any brand that would rather be recognised nationally than be locally placed.

Choose national over several local numbers when one point of contact is worth more than regional familiarity, and when consolidating means fewer numbers to pay for and register.

A number the called party pays for. The caller is not billed, so a toll-free number is what you publish when you want the cost of reaching you never to be a reason not to. In North America toll-free numbers can also carry messaging.

Toll-free is its own registration program rather than a variation on a long code, and sending messaging traffic from one means completing that program first.

A short code is four to six digits instead of a full number, which makes it easy to remember and, in North America, gives the highest messaging throughput of any sender. It works nationally only: a short code cannot be reached from a foreign number, and it carries no voice service.

Two type values cover them. short_code is an ordinary short code. short_code_fteu is a free-to-end-user short code, one whose traffic is not billed to the subscriber.

Short codes are not self-serve. A short code reaches your workspace by allocation from Bird rather than by purchase, and it arrives with kind: shared: there is no monthly charge of your own, and you cannot release it. Ordering one through the numbers API is refused. A search may still return short_code rows, so treat those as a catalogue of what exists rather than as an offer, and contact us to be allocated one.

A number proves ownership under its own type: the registration program a country runs for a toll_free number is a different program from the one it runs for a local one, and completing the wrong one does not unblock sending. The number's ownership field names what is still outstanding and which call advances it, and a number waiting on it sits at pending_compliance while still being billed. Numbers overview covers that lifecycle.

Two programs come up often enough to name here. A US long code, whether mobile, local or national, needs a registered brand and campaign before it can carry application-to-person traffic; 10DLC registration covers the model and what a workspace prepares. A toll-free number carrying messaging needs toll-free verification. Both are registrations of the sender, separate from and additional to owning the number.