Numbers: buy and manage phone numbers over the API

The numbers your workspace sends from are now yours to manage over the API. Search what is on sale in a country, order one, and release it when you are done, without opening the dashboard.

Buying a number was a dashboard task, which meant provisioning could not be part of anything automated: onboarding a customer onto their own number, or giving a new region its own local presence, ended at a form somebody had to fill in. These are the same operations the dashboard has been using, now published.

What's new

• Search, scoped to a country. GET /v1/numbers/available takes a country_code and narrows from there by type, capability, or a prefix of national digits. Bird's own stock pages normally; the last page can include what a carrier is offering live.
• Buying is an order you can follow. POST /v1/numbers/orders usually completes inside the request and hands back the number. One that has to wait on a carrier comes back still running, and GET /v1/numbers/orders/{order_id} polls it to completed or failed. Send an Idempotency-Key and a retry cannot buy twice.
• Read and release what you hold. GET /v1/numbers lists your numbers with their type, capabilities, and status; DELETE /v1/numbers/{number_id} releases a dedicated one and stops its monthly charge.
• Typed in every SDK. numbers.available.list, numbers.orders.create, numbers.list and numbers.release are methods in the Go, TypeScript, Python, and PHP SDKs, each with a worked example.

An API key needs the new numbers scope, and the first purchase in an organization needs identity verification. Buy and release a number walks the whole flow, and Numbers overview explains what the fields on a number mean.