# 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. Alles hier erfordert einen API-Schlüssel mit dem Scope `numbers`, und der erste Kauf in einer Organisation erfordert eine Identitätsprüfung.

## 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.

**TypeScript**

```typescript
// 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);
}
```

Examples: [TypeScript](/de-de/dokumentation/guides/numbers/buying-numbers.ts.md) · [Python](/de-de/dokumentation/guides/numbers/buying-numbers.py.md) · [Go](/de-de/dokumentation/guides/numbers/buying-numbers.go.md) · [PHP](/de-de/dokumentation/guides/numbers/buying-numbers.php.md) · [cURL](/de-de/dokumentation/guides/numbers/buying-numbers.curl.md)

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 enthält nur das, was Sie für die Auswahl brauchen:

```json
{
  "data": [
    {
      "number": "+447700900123",
      "country_code": "GB",
      "number_type": "mobile",
      "capabilities": ["sms", "voice"]
    }
  ],
  "next_cursor": null,
  "prev_cursor": null
}
```

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 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}`](/docs/api/reference/get-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`](/docs/api/reference/create-numbers-order). Zum Schutz vor doppelten Anfragen siehe [Idempotenz](/docs/guides/idempotency).

**TypeScript**

```typescript
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);
}
```

Examples: [TypeScript](/de-de/dokumentation/guides/numbers/buying-numbers.ts.md) · [Python](/de-de/dokumentation/guides/numbers/buying-numbers.py.md) · [Go](/de-de/dokumentation/guides/numbers/buying-numbers.go.md) · [PHP](/de-de/dokumentation/guides/numbers/buying-numbers.php.md) · [MCP](/de-de/dokumentation/guides/numbers/buying-numbers.mcp.md) · [cURL](/de-de/dokumentation/guides/numbers/buying-numbers.curl.md)

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

```json
{
  "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.

**TypeScript**

```typescript
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 ?? "");
```

Examples: [TypeScript](/de-de/dokumentation/guides/numbers/buying-numbers.ts.md) · [Python](/de-de/dokumentation/guides/numbers/buying-numbers.py.md) · [Go](/de-de/dokumentation/guides/numbers/buying-numbers.go.md) · [PHP](/de-de/dokumentation/guides/numbers/buying-numbers.php.md) · [MCP](/de-de/dokumentation/guides/numbers/buying-numbers.mcp.md) · [cURL](/de-de/dokumentation/guides/numbers/buying-numbers.curl.md)

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 monatliche 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.

**TypeScript**

```typescript
// 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");
```

Examples: [TypeScript](/de-de/dokumentation/guides/numbers/buying-numbers.ts.md) · [Python](/de-de/dokumentation/guides/numbers/buying-numbers.py.md) · [Go](/de-de/dokumentation/guides/numbers/buying-numbers.go.md) · [PHP](/de-de/dokumentation/guides/numbers/buying-numbers.php.md) · [MCP](/de-de/dokumentation/guides/numbers/buying-numbers.mcp.md) · [cURL](/de-de/dokumentation/guides/numbers/buying-numbers.curl.md)

Eine erfolgreiche Freigabe antwortet mit `204` ohne Body.

## Wenn eine Bestellung abgelehnt wird

Vier Ablehnungsgründe decken nahezu jeden fehlgeschlagenen Kauf ab.

`402` mit [`E03000`](/docs/api/errors/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 Identitätsprüfung noch nicht abgeschlossen hat. Schließen Sie sie ab und versuchen Sie es erneut.

`409` mit [`E14000`](/docs/api/errors/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`](/docs/api/errors/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

- [Nummern – Übersicht](/docs/guides/numbers/overview) erklärt, was die Felder einer Nummer bedeuten.
- [Numbers API – Referenz](/docs/api/reference/create-numbers-order) dokumentiert jede Operation und jedes Feld.
- [Idempotenz](/docs/guides/idempotency) erklärt, wie Schlüssel eine erneut gesendete Bestellung sicher machen.

## Related resources

- [What is a virtual phone number (VMN)?](/explained/numbers/what-is-a-virtual-phone-number) (answer)
- [SMS numbers](/sms-api/features/numbers) (product)
- [Number types](/docs/guides/numbers/number-types) (docs)

[Get an implementation brief](/learn/workspace?topic=phone-numbers)