Sign inGet Started

Een nummer kopen en vrijgeven

Een nummer kopen kost twee calls: zoek in een land wat er beschikbaar is en bestel het nummer dat je wilt. Alles hier vereist een API-key met de numbers-scope, en de eerste aankoop in een organisatie vereist identiteitsverificatie.

Zoek in een land

De zoekopdracht is altijd beperkt tot één land, dus country_code is verplicht. Verfijn verder met number_type, capabilities, of een prefix van nationale cijfers.
// The search is always country-scoped, so country_code is required.
const page = await bird.numbers.available.list({
  country_code: "GB",
  capabilities: ["sms", "voice"],
});
for (const candidate of page.data) {
  console.log(candidate.number, candidate.number_type);
}
Gebruik de regionale host die overeenkomt met het bk_{region}_-prefix van je key: https://us1.platform.bird.com of https://eu1.platform.bird.com.
Elk resultaat bevat alleen wat je nodig hebt om er een te kiezen:
Codevoorbeeld
{
  "data": [
    {
      "number": "+447700900123",
      "country_code": "GB",
      "number_type": "mobile",
      "capabilities": ["sms", "voice"]
    }
  ],
  "next_cursor": null,
  "prev_cursor": null
}
Onze eigen voorraad wordt eerst geretourneerd en pagineert normaal. De laatste pagina kan nummers bevatten die een carrier live aanbiedt, dus een nummer dat zojuist vermeld stond kan al weg zijn tegen de tijd dat je het bestelt.
Om te bevestigen dat een nummer nog beschikbaar is voordat je het bestelt, lees je het terug met GET /v1/numbers/available/{number}. Een 404 betekent dat het nummer momenteel niet te koop is, of een provider het heeft ingetrokken of onze eigen voorraad het heeft gereserveerd. De hercontrole valt onder dezelfde numbers_availability-limiet als de zoekopdracht, dus controleer alleen het nummer dat je wilt bestellen, niet elk resultaat.

Het nummer bestellen

Geef een nummer uit de zoekresultaten door aan POST /v1/numbers/orders. Zie Idempotentie voor bescherming bij opnieuw proberen.
const order = await bird.numbers.orders.create({ number: "+447700900201" });
// Most orders finish inside the request. One that has to wait on a carrier
// comes back without a number_id. Poll it until it is completed or failed.
if (order.status === "completed") {
  console.log("allocated as", order.number_id);
} else {
  console.log("still", order.status, "; poll", order.id);
}
De meeste bestellingen worden binnen het request afgerond en beantwoorden 201 met het nummer al op jouw naam:
Codevoorbeeld
{
  "id": "nor_01m0da22b0e39anhzyhtw3gzdg",
  "number": "+447700900123",
  "country_code": "GB",
  "number_type": "mobile",
  "status": "completed",
  "number_id": "nda_7eqywfwzxwa1za9n8wp7e1xkr8",
  "failure_reason": null,
  "completed_at": "2026-08-19T15:25:56.479320Z",
  "created_at": "2026-08-19T15:25:56.448051Z",
  "updated_at": "2026-08-19T15:25:56.479320Z"
}
number_id is het handvat voor alles hierna: het nummer uitlezen en vrijgeven.

Een bestelling pollen die niet direct afgerond is

Een bestelling die op een provider moet wachten beantwoordt in plaats daarvan 202, met number_id nog op null. Lees de bestelling opnieuw uit totdat status gelijk is aan completed of failed.
const order = await bird.numbers.orders.get("nor_01krdgeqcxet5s7t44vh8rt9mg");
// failure_reason says what went wrong, and only ever on a failed order.
console.log(order.status, order.failure_reason ?? "");
Een bestelling doorloopt charging, ordering en pending voordat deze definitief is. Bij failed beschrijft failure_reason in begrijpelijke termen wat er misging. Een al afgeschreven activatietarief wordt niet terugbetaald, dus een mislukte bestelling kan een kostenpost achterlaten; neem in dat geval contact op met support.

Een nummer vrijgeven

Vrijgeven stopt de maandelijkse kosten en het nummer werkt niet meer voor je. Alleen een dedicated-nummer kan worden vrijgegeven, en een vrijgegeven nummer komt niet meteen weer te koop.
// Releasing stops the monthly charge and the number stops working for you.
// Only a dedicated number can be released; a shared one answers E14002.
await bird.numbers.release("nda_01krdgeqcxet5s7t44vh8rt9mg");
Een geslaagde vrijgave beantwoordt 204 zonder body.

Wanneer een bestelling wordt geweigerd

Vier weigeringen dekken vrijwel elke mislukte aankoop.
402 met E03000 betekent dat het saldo het nummer niet dekt. Vul het saldo aan en bestel opnieuw. Er wordt geen bestelling aangemaakt, dus er worden geen kosten in rekening gebracht.
412 betekent dat de organisatie de identiteitsverificatie die een eerste aankoop vereist nog niet heeft afgerond. Rond deze af en probeer het opnieuw.
409 met E14000 betekent dat het nummer weg was terwijl je aan het kiezen was. Zoek opnieuw en kies een ander nummer.
409 met E14001 betekent dat te veel van je bestellingen al in behandeling zijn. Wacht tot er een is afgerond en bestel dan opnieuw.

Volgende stappen