Managing your phone numbers

Once a number is allocated to your workspace, the numbers API lets you list what you hold, find one number by any of its handles, label it with a name and your own reference, and release it when you are done. Reading needs an API key with the numbers scope at read level; changing or releasing a number needs write level.

The Numbers page in the dashboard shows the same numbers.

List every number you hold

GET /v1/numbers returns the numbers currently allocated to your workspace, newest first, dedicated and shared alike. Each page holds 25 numbers unless you ask for up to 100 with limit.

The list is paged by cursor. Pass a page's next_cursor back as starting_after to read the next page, and stop when next_cursor is null. The SDKs follow the cursor for you. The examples below narrow the list to country_code: "GB"; leave the filter out to walk every number you hold:

for await (const allocated of bird.numbers.list({ country_code: "GB" })) {
  // kind distinguishes a number you bought from one Bird manages.
  console.log(allocated.number, allocated.kind, allocated.status);
}

for allocated in client.numbers.list(country_code="GB"):
    # kind distinguishes a number you bought from one Bird manages.
    print(allocated.number, allocated.kind, allocated.status)

for allocated, err := range client.Numbers.List(context.Background(), bird.NumbersListParams{
	CountryCode: "GB",
}) {
	if err != nil {
		log.Fatal(err)
	}
	// Kind distinguishes a number you bought from one Bird manages.
	fmt.Println(allocated.Number, allocated.Kind, allocated.Status)
}

$page = $bird->numbers->list(['country_code' => 'GB']);
foreach ($page as $allocated) {
    // kind distinguishes a number you bought from one Bird manages.
    echo $allocated->getNumber(), ' ', $allocated->getKind(), ' ', $allocated->getStatus(), "\n";
}

curl "https://us1.platform.bird.com/v1/numbers?country_code=GB" \
  -H "Authorization: Bearer bk_us1_..."

Use the regional host that matches your key's bk_{region}_ prefix: https://us1.platform.bird.com or https://eu1.platform.bird.com.

The list carries no total. To count your numbers, walk the pages to the end and count the entries. Passing include_total is refused with 422 and E01029.

Each entry carries its status and ownership. Where a country asks for no ownership paperwork, ownership is null. The Numbers overview explains what each status means.

Find a number in your list

The list filters combine, so a country or capability filter still applies alongside the others.

number looks up one number however your records spell it. +31612345678 and 0031612345678 resolve to the same number. A national spelling such as 0612345678 resolves only when country_code names the country:

curl "https://us1.platform.bird.com/v1/numbers?number=0612345678&country_code=NL" \
  -H "Authorization: Bearer bk_us1_..."

When you pass a full number, or a national spelling with its country_code, and no other filter, an empty data array means the number is not allocated to your workspace, which includes a number you have released. A national spelling without country_code, such as 0612345678 on its own, also returns an empty list, so it does not prove the number is not yours.

search matches part of the number, its name, or its reference, ignoring case. reference returns the numbers with exactly that reference, matching case:

curl "https://us1.platform.bird.com/v1/numbers?reference=STORE-042" \
  -H "Authorization: Bearer bk_us1_..."

prefix returns numbers that start with the digits you give, and what those digits mean depends on country_code:

• With country_code, the digits are national ones, matched right after the dial code. prefix=6&country_code=NL returns Dutch numbers that start +31 6.
• Without country_code, the digits are matched from the start of the full number. prefix=6 on its own returns numbers whose dial code starts with 6, such as Australian +61 numbers, so it finds none of your Dutch mobiles. It also matches short codes that start with those digits.

Name a number and set your reference

A number carries two labels of your own. name tells your numbers apart, such as Support line. reference holds an identifier from your own records, such as a customer or store id, and it need not be unique. Both apply to dedicated and shared numbers and are up to 100 characters.

Set them with PATCH /v1/numbers/{number_id}. A field you omit keeps its current value, and a field you send as null is cleared. Leading and trailing whitespace is removed.

const allocated = await bird.numbers.update("nda_01krdgeqcxet5s7t44vh8rt9mg", {
  name: "Support line",
  reference: "STORE-042",
});
console.log(allocated.name, allocated.reference);

allocated = client.numbers.update(
    "nda_01krdgeqcxet5s7t44vh8rt9mg", name="Support line", reference="STORE-042"
)
print(allocated.name, allocated.reference)

allocated, err := client.Numbers.Update(ctx, "nda_01krdgeqcxet5s7t44vh8rt9mg", bird.NumbersUpdateParams{
	Name:      bird.Value("Support line"),
	Reference: bird.Value("STORE-042"),
})
if err != nil {
	log.Fatal(err)
}
if allocated.Name != nil {
	fmt.Println(*allocated.Name)
}
if allocated.Reference != nil {
	fmt.Println(*allocated.Reference)
}

$allocated = $bird->numbers->update(
    'nda_01krdgeqcxet5s7t44vh8rt9mg',
    (new \MessageBird\Wire\Model\NumberUpdate())->setName('Support line')->setReference('STORE-042'),
);
echo $allocated->getName(), ' ', $allocated->getReference(), "\n";

curl -X PATCH "https://{region}.platform.bird.com/v1/numbers/{number_id}" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Support line",
    "reference": "STORE-042"
  }'

The response is 200 with the updated number. To clear the reference and keep the name, send the reference as null and leave the name out:

curl -X PATCH "https://us1.platform.bird.com/v1/numbers/nda_01krdgeqcxet5s7t44vh8rt9mg" \
  -H "Authorization: Bearer bk_us1_..." \
  -H "Content-Type: application/json" \
  -d '{"reference": null}'

To set the reference when you buy the number, pass reference on POST /v1/numbers/orders. An order that has to wait on a carrier keeps the reference until the number is allocated, and the number carries it from then on.

Find the voice record that routes a number

A number that carries voice has two identifiers. The id on GET /v1/numbers starts with nda_ for a dedicated number and nal_ for a shared one, and the numbers operations take it. The voice operations, including the one that sets where incoming calls go, take the number's voice record, whose id starts with vnu_. Passing an nda_ id to a voice operation is refused with 422.

To get from one to the other, search the voice numbers by the phone number. This needs the voice_management scope at read level:

curl "https://us1.platform.bird.com/v1/voice/numbers?search=%2B31612345678" \
  -H "Authorization: Bearer bk_us1_..."

The entry's id is the vnu_ identifier, and its provider.number_id is the nda_ identifier of the same number. Receiving calls shows how to route the number from there.

The voice record has a name of its own. Naming a number with PATCH /v1/numbers/{number_id} leaves the voice record's name unchanged, and the reverse holds too.

Release a number

Releasing a dedicated number with DELETE /v1/numbers/{number_id} takes effect immediately. Buy and release a number shows the call in each SDK.

Send a release with an Idempotency-Key so a retry is safe: the same key replays the 204 with an Idempotency-Replay: true header, while a new request for a number already released answers 404 with E01008. Idempotency explains how long a key is kept.

After the release:

• The number stops working for you, and its subscription ends with the period you already paid for instead of renewing.
• GET /v1/numbers/{number_id} and the number's voice record answer 404, and the number leaves GET /v1/numbers.
• The number's order stays in GET /v1/numbers/orders, and its number_id now answers 404.
• The number goes into a 30-day cooldown before it can return to sale, so you cannot buy the same number back straight away.

Next steps

• Receiving calls routes a number to a SIP trunk, a forward, or a sequence.
• Buy and release a number walks the purchase over the API.
• Numbers API reference documents every operation and field.