Eine Nummer kaufen und freigeben

Der Kauf einer Nummer erfordert zwei Aufrufe: Durchsuchen Sie ein Land nach verfügbaren Nummern und bestellen Sie dann die gewünschte. Für alle Schritte hier benötigen Sie einen API-Schlüssel mit dem Scope numbers, und der erste Kauf in einer Organisation erfordert eine Verifizierung der Identität.

Ein Land durchsuchen

Die Suche ist immer auf ein Land beschränkt, daher ist country_code erforderlich. Grenzen Sie weiter ein mit number_type, capabilities oder einem prefix nationaler Ziffern.

// 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_..."

Verwenden Sie den regionalen Host, der zum bk_{region}_-Präfix Ihres Schlüssels passt: https://us1.platform.bird.com oder https://eu1.platform.bird.com.

Jedes Ergebnis beschreibt die Nummer:

Codebeispiel

{
  "data": [
    {
      "number": "+447700900123",
      "country_code": "GB",
      "number_type": "mobile",
      "capabilities": ["sms", "voice"],
      "pricing": {
        "setup_price": { "amount": "0.00995", "currency_code": "USD" },
        "recurring_price": { "amount": "0.00995", "currency_code": "USD" },
        "recurring_period": { "unit": "month", "count": 1 },
        "intervals_per_charge": 12
      }
    }
  ],
  "next_cursor": null,
  "prev_cursor": null
}

Jedes Ergebnis enthält außerdem ein pricing-Objekt mit dem Preis für Ihre Organisation, netto ohne Steuern und in Ihrer Abrechnungswährung:

setup_price wird einmalig bei der Bestellung der Nummer berechnet. Eine veröffentlichte Gebühr von null hat einen amount von "0". Das Feld selbst ist null, wenn keine Einrichtungsgebühr anfällt, und außerdem immer dann, wenn recurring_price den Wert null hat, weil diese Nummer nicht bestellt werden kann.
recurring_price ist der Tarif pro recurring_period.
intervals_per_charge gibt an, wie viele recurring_periods eine Abbuchung umfasst. Die wiederkehrende Gebühr vor Steuern ergibt sich aus recurring_price multipliziert mit intervals_per_charge und wird abgebucht, wenn die Nummer Ihrem Workspace zugewiesen wird, sowie bei jeder Verlängerung. Bei einer Bestellung, die auf einen Carrier wartet, erfolgt die Zuweisung, sobald die Bestellung abgeschlossen ist. Eine recurring_period von einem Monat mit intervals_per_charge: 12 rechnet 12 Monate auf einmal ab.

Die API-Referenz zeigt ein Beispielergebnis mit Preisen. Ein Suchergebnis mit pricing.recurring_price: null nennt keinen wiederkehrenden Preis. Kontaktieren Sie den Vertrieb, um vor der Bestellung einen Preis für dieses Land und diesen Nummerntyp zu erhalten.

Das Dashboard und API verwenden denselben Organisationspreis, einschließlich der Umrechnung in Ihre Abrechnungswährung. Ein Preisabruf sichert kein Angebot: Tarif- oder Wechselkursänderungen vor einer späteren Abbuchung können deren Betrag verändern. Wenn der Abruf fehlschlägt, gibt die Suche 503 mit E14009 zurück. Versuchen Sie den Abruf mit exponentiellem Backoff erneut; ein fehlgeschlagener Abruf bedeutet nie, dass die Nummer nichts kostet.

Unser eigener Bestand wird zuerst zurückgegeben und paginiert normal. Die letzte Seite kann Nummern enthalten, die ein Carrier live anbietet. Eine Nummer, die gerade noch gelistet war, kann daher zum Zeitpunkt Ihrer Bestellung bereits vergeben sein.

Um vor der Bestellung zu prüfen, ob eine Nummer noch verfügbar ist, rufen Sie sie mit GET /v1/numbers/available/{number} ab. Ein 404 bedeutet, dass sie derzeit nicht zum Kauf verfügbar ist, egal ob ein Carrier sie zurückgezogen hat oder unser eigener Bestand sie reserviert hält. Die Nachprüfung nutzt dasselbe numbers_availability-Rate-Limit wie die Suche. Prüfen Sie daher nur den Kandidaten, den Sie bestellen möchten, und nicht jedes Ergebnis.

Die Nummer bestellen

Übergeben Sie eine Nummer aus der Suche an POST /v1/numbers/orders. Zum Schutz bei erneutem Versuch siehe Idempotenz.

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"}'

Die meisten Bestellungen werden innerhalb des Requests abgeschlossen und antworten mit 201, wobei die Nummer bereits Ihnen gehört:

Codebeispiel

{
  "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 ist das Handle für alles Weitere: die Nummer lesen und freigeben.

Eine nicht abgeschlossene Bestellung abfragen

Eine Bestellung, die auf einen Carrier warten muss, antwortet stattdessen mit 202, wobei number_id noch null ist. Rufen Sie sie erneut ab, bis status den Wert completed oder failed hat.

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_..."

Eine Bestellung durchläuft charging, ordering und pending, bevor sie abgeschlossen ist. Bei failed beschreibt failure_reason in verständlichen Worten, was schiefgelaufen ist. Eine bereits erhobene Einrichtungsgebühr wird nicht erstattet, eine fehlgeschlagene Bestellung kann also eine Belastung hinterlassen; wenden Sie sich in diesem Fall an den Support.

Eine Nummer freigeben

Die Freigabe beendet die wiederkehrende Gebühr, und die Nummer funktioniert nicht mehr für Sie. Nur eine dedicated-Nummer kann freigegeben werden, und eine freigegebene Nummer wird nicht sofort wieder zum Verkauf angeboten.

// Releasing stops the recurring 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 recurring 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 recurring 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 POST "https://us1.platform.bird.com/v1/numbers/nda_7eqywfwzxwa1za9n8wp7e1xkr8/release" \
  -H "Authorization: Bearer bk_us1_..."

Eine erfolgreiche Freigabe antwortet mit 204 ohne Body. Um die Nummer bis zum Ende des bereits bezahlten Zeitraums zu behalten, stornieren Sie sie stattdessen: Ihre Telefonnummern verwalten erklärt beide Optionen.

Wenn eine Bestellung abgelehnt wird

Vier Ablehnungsgründe decken fast jeden fehlgeschlagenen Kauf ab.

402 mit E03000 bedeutet, dass das Guthaben nicht für die Nummer ausreicht. Laden Sie es auf und bestellen Sie erneut. Es wird keine Bestellung angelegt, daher entstehen keine Kosten.

412 bedeutet, dass die Organisation die für einen Erstkauf erforderliche Verifizierung der Identität noch nicht abgeschlossen hat. Schließen Sie sie ab und versuchen Sie es dann erneut.

409 mit E14000 bedeutet, dass die Nummer vergeben wurde, während Sie sie ausgewählt haben. Suchen Sie erneut und wählen Sie eine andere.

409 mit E14001 bedeutet, dass zu viele Ihrer Bestellungen bereits in Bearbeitung sind. Warten Sie, bis eine abgeschlossen ist, und bestellen Sie dann erneut.

Nächste Schritte

Die Nummernübersicht erklärt, was die Felder einer Nummer bedeuten.
Die Numbers-API-Referenz dokumentiert jede Operation und jedes Feld.
Idempotenz erklärt, wie Schlüssel eine erneut gesendete Bestellung sicher machen.

Weiter mit der Dokumentation, Anleitungen und Beispielen zu diesem Thema.

Implementierungs-Briefing erhalten