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](/docs/guides/numbers/buying-numbers) walks the whole flow, and [Numbers overview](/docs/guides/numbers/overview) explains what the fields on a number mean.