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);
}# The search is always country-scoped, so country_code is required.
page = client.numbers.available.list(country_code="GB", capabilities=["sms", "voice"])
for candidate in page.data:
print(candidate.number, candidate.number_type)for candidate, err := range client.Numbers.Available.List(context.Background(), bird.NumbersAvailableListParams{
CountryCode: "GB",
Capabilities: []string{"sms", "voice"},
}) {
if err != nil {
log.Fatal(err)
}
fmt.Println(candidate.Number, candidate.NumberType)
}// The search is always country-scoped, so country_code is required.
$page = $bird->numbers->available->list([
'country_code' => 'GB',
'capabilities' => ['sms', 'voice'],
]);
foreach ($page as $candidate) {
echo $candidate->getNumber(), ' ', $candidate->getNumberType(), "\n";
}curl "https://us1.platform.bird.com/v1/numbers/available?country_code=GB" \
-H "Authorization: Bearer bk_us1_..."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);
}order = client.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 completed or failed.
if order.status == "completed":
print("allocated as", order.number_id)
else:
print("still", order.status, "; poll", order.id)order, err := client.Numbers.Orders.Create(context.Background(), bird.NumbersOrdersCreateParams{
Number: "+447700900201",
})
if err != nil {
log.Fatal(err)
}
// An order that has to wait on a carrier comes back without a NumberId.
// Poll it until it is completed or failed.
fmt.Println(order.Status, order.Id)$order = $bird->numbers->orders->create(
(new NumbersOrderCreate())->setNumber('+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->getStatus() === 'completed') {
echo 'allocated as ', $order->getNumberId(), "\n";
} else {
echo 'still ', $order->getStatus(), '; poll ', $order->getId(), "\n";
}curl -X POST "https://us1.platform.bird.com/v1/numbers/orders" \
-H "Authorization: Bearer bk_us1_..." \
-H "Content-Type: application/json" \
-d '{"number": "+447700900123"}'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 ?? "");order = client.numbers.orders.get("nor_01krdgeqcxet5s7t44vh8rt9mg")
# failure_reason says what went wrong, and only ever on a failed order.
print(order.status, order.failure_reason or "")order, err := client.Numbers.Orders.Get(context.Background(), "nor_01krdgeqcxet5s7t44vh8rt9mg")
if err != nil {
log.Fatal(err)
}
// FailureReason says what went wrong, and only ever on a failed order.
fmt.Println(order.Status)$order = $bird->numbers->orders->get('nor_01krdgeqcxet5s7t44vh8rt9mg');
// failure_reason says what went wrong, and only ever on a failed order.
echo $order->getStatus(), ' ', $order->getFailureReason() ?? '', "\n";curl "https://us1.platform.bird.com/v1/numbers/orders/nor_01m0da22b0e39anhzyhtw3gzdg" \
-H "Authorization: Bearer bk_us1_..."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");# Releasing stops the monthly charge and the number stops working for you.
# Only a dedicated number can be released; a shared one answers E14002.
client.numbers.release("nda_01krdgeqcxet5s7t44vh8rt9mg")// Only a dedicated number can be released; a shared one answers E14002.
if err := client.Numbers.Release(context.Background(), "nda_01krdgeqcxet5s7t44vh8rt9mg"); err != nil {
log.Fatal(err)
}// Releasing stops the monthly charge and the number stops working for you.
// Only a dedicated number can be released; a shared one answers E14002.
$bird->numbers->release('nda_01krdgeqcxet5s7t44vh8rt9mg');curl -X DELETE "https://us1.platform.bird.com/v1/numbers/nda_7eqywfwzxwa1za9n8wp7e1xkr8" \
-H "Authorization: Bearer bk_us1_..."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
- Overzicht van nummers legt uit wat de velden op een nummer betekenen.
- Numbers API-referentie documenteert elke bewerking en elk veld.
- Idempotentie legt uit hoe sleutels een herhaalde bestelling veilig maken.
Gerelateerde bronnen
Ga verder met de documentatie, handleidingen en voorbeelden voor dit onderwerp.