---
title: "Ihre Telefonnummern verwalten"
description: "Listen Sie die Ihrem Workspace zugewiesenen Nummern auf, finden Sie sie, versehen Sie sie mit einem Namen und Ihrer eigenen Referenz, rufen Sie den zugehörigen Voice-Eintrag ab, und kündigen oder geben Sie sie über die API frei."
canonical: "https://bird.com/de-de/dokumentation/guides/numbers/managing-numbers"
---

# Ihre Telefonnummern verwalten

Sobald eine Nummer Ihrem Workspace zugewiesen ist, können Sie über die Numbers-API auflisten, was Sie halten, eine Nummer anhand beliebiger Kennungen finden, sie mit einem Namen und Ihrer eigenen Referenz versehen und sie kündigen oder freigeben, wenn Sie sie nicht mehr benötigen. Zum Lesen benötigen Sie einen API-Schlüssel mit dem Scope `numbers` auf Lesestufe; zum Ändern, Kündigen oder Freigeben einer Nummer ist Schreibstufe erforderlich.

Die Seite [**Numbers**](https://bird.com/dashboard/w/numbers) im Dashboard zeigt dieselben Nummern.

## Alle Nummern auflisten, die Sie halten

[`GET /v1/numbers`](/docs/api/reference/list-workspace-numbers) gibt die Nummern zurück, die Ihrem Workspace aktuell zugewiesen sind, neueste zuerst, dedizierte und geteilte gleichermaßen. Jede Seite enthält 25 Nummern, sofern Sie nicht mit `limit` bis zu 100 anfordern.

Die Liste ist per Cursor paginiert. Übergeben Sie den `next_cursor` einer Seite als `starting_after`, um die nächste Seite zu lesen, und stoppen Sie, wenn `next_cursor` den Wert `null` hat. Die SDKs folgen dem Cursor automatisch. Die folgenden Beispiele schränken die Liste auf `country_code: "GB"` ein; lassen Sie den Filter weg, um alle Nummern durchzugehen, die Sie halten:

**TypeScript**

```typescript
for await (const allocated of bird.numbers.list({ country_code: "GB" })) {
  console.log(allocated.number, allocated.kind, allocated.status);
}
```

Examples: [TypeScript](/de-de/dokumentation/guides/numbers/managing-numbers.ts.md) · [Python](/de-de/dokumentation/guides/numbers/managing-numbers.py.md) · [Go](/de-de/dokumentation/guides/numbers/managing-numbers.go.md) · [PHP](/de-de/dokumentation/guides/numbers/managing-numbers.php.md) · [MCP](/de-de/dokumentation/guides/numbers/managing-numbers.mcp.md) · [cURL](/de-de/dokumentation/guides/numbers/managing-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`.

Die Liste enthält keine Gesamtzahl. Um Ihre Nummern zu zählen, durchlaufen Sie alle Seiten bis zum Ende und zählen die Einträge. Die Übergabe von `include_total` wird mit `422` und [`E01029`](/docs/api/errors/E01029) abgelehnt.

Jeder Eintrag enthält seinen `status` und `ownership`. Wenn ein Land keine Eigentumsnachweise verlangt, ist `ownership` gleich `null`. Die [Numbers-Übersicht](/docs/guides/numbers/overview#the-status-of-an-allocated-number) erklärt, was jeder Status bedeutet. Wie Sie die Eigentumsnachweise einreichen, auf die eine Nummer wartet, erfahren Sie unter [Eigentumsnachweise für eine Nummer einreichen](/docs/guides/numbers/ownership-paperwork).

Jeder Eintrag enthält außerdem `pricing`, also den Betrag, den Ihre Organisation für die Nummer zahlt, netto ohne Steuern:

- `recurring_price` ist Ihr Tarif pro `recurring_period`, in der Währung, in der die Nummer abgerechnet wird. Das ist Ihre Abrechnungswährung, es sei denn, das Abonnement der Nummer begann, bevor sich Ihre Abrechnungswährung geändert hat; eine solche Nummer behält die Währung ihres Abonnements, die `currency_code` angibt.
- `intervals_per_charge` gibt an, wie viele `recurring_period`s eine Verlängerung abrechnet. Die wiederkehrende Gebühr vor Steuern ist `recurring_price` multipliziert mit `intervals_per_charge`. Ein für die Nummer festgelegter Preis deckt den gesamten Zeitraum ab, daher ist sein `intervals_per_charge` gleich `1`.

`pricing` ist `null` bei einer `shared`-Nummer und bei einer Nummer ohne aktives Abonnement. Wenn für das Abonnement einer Nummer kein Preis gilt, sind ihre Preise `null` mit `pricing.error: null`; [kontaktieren Sie den Vertrieb](/contact-sales), um einen Preis dafür zu erhalten. Wenn der Preis nicht gelesen werden konnte, enthält `pricing.error` den Wert [`E14009`](/docs/api/errors/E14009) und die Preise sind `null`. Versuchen Sie [`GET /v1/numbers/{number_id}`](/docs/api/reference/get-workspace-number) mit exponentiellem Backoff erneut. Die Nummer bleibt verwaltbar; wiederholen Sie ein bereits abgeschlossenes Update oder eine abgeschlossene Kündigung nicht, um ihren Preis zu aktualisieren.

Dashboard und API verwenden dieselbe Preisermittlung. Ein fester Preis behält seine bestehenden Bedingungen; andernfalls ist dies der aktuelle Tarif, der sich vor der Verlängerung ändern kann. Er gibt nicht an, was eine frühere Bestellung berechnet hat. Eine Nummer mit gesetztem `releases_at` behält ihr `pricing` bis zur Freigabe, und es folgt keine Verlängerung.

## Eine Nummer in Ihrer Liste finden

Die Listenfilter werden kombiniert, sodass ein Länder- oder Fähigkeitsfilter weiterhin zusammen mit den anderen gilt.

`number` sucht eine einzelne Nummer, egal wie Ihre Einträge sie schreiben. `+31612345678` und `0031612345678` werden zur selben Nummer aufgelöst. Eine nationale Schreibweise wie `0612345678` wird nur aufgelöst, wenn `country_code` das Land angibt:

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

Wenn Sie eine vollständige Nummer oder eine nationale Schreibweise mit ihrem `country_code` ohne weiteren Filter übergeben, bedeutet ein leeres `data`-Array, dass die Nummer nicht Ihrem Workspace zugewiesen ist. Das schließt eine von Ihnen freigegebene Nummer ein. Eine nationale Schreibweise ohne `country_code`, etwa `0612345678` allein, gibt ebenfalls eine leere Liste zurück und beweist daher nicht, dass die Nummer nicht Ihnen gehört.

`search` gleicht einen Teil der Nummer, ihres Namens oder ihrer Referenz ab, ohne Berücksichtigung der Groß-/Kleinschreibung. `reference` gibt die Nummern mit exakt dieser Referenz zurück, unter Berücksichtigung der Groß-/Kleinschreibung:

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

`prefix` gibt Nummern zurück, die mit den angegebenen Ziffern beginnen, und die Bedeutung dieser Ziffern hängt von `country_code` ab:

- Mit `country_code` sind die Ziffern nationale Ziffern, die direkt nach der Landesvorwahl abgeglichen werden. `prefix=6&country_code=NL` gibt niederländische Nummern zurück, die mit `+31 6` beginnen.
- Ohne `country_code` werden die Ziffern ab dem Anfang der vollständigen Nummer abgeglichen. `prefix=6` allein gibt Nummern zurück, deren Landesvorwahl mit 6 beginnt, etwa australische `+61`-Nummern, und findet daher keine Ihrer niederländischen Mobilnummern. Es werden auch Kurzcodes gefunden, die mit diesen Ziffern beginnen.

## Einer Nummer einen Namen geben und Ihre Referenz setzen

Eine Nummer trägt zwei eigene Labels. `name` unterscheidet Ihre Nummern voneinander, zum Beispiel `Support line`. `reference` enthält einen Bezeichner aus Ihren eigenen Einträgen, etwa eine Kunden- oder Filial-ID, und muss nicht eindeutig sein. Beide gelten für dedizierte und geteilte Nummern und sind bis zu 100 Zeichen lang.

Setzen Sie sie mit [`PATCH /v1/numbers/{number_id}`](/docs/api/reference/update-workspace-number). Ein Feld, das Sie weglassen, behält seinen aktuellen Wert, und ein Feld, das Sie als `null` senden, wird gelöscht. Führende und abschließende Leerzeichen werden entfernt.

**TypeScript**

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

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

Die Antwort ist `200` mit der aktualisierten Nummer. Um die Referenz zu löschen und den Namen beizubehalten, senden Sie die Referenz als `null` und lassen Sie den Namen weg:

```bash
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}'
```

Um die Referenz beim Kauf der Nummer zu setzen, übergeben Sie `reference` bei [`POST /v1/numbers/orders`](/docs/api/reference/create-numbers-order). Eine Bestellung, die auf einen Carrier warten muss, behält die Referenz, bis die Nummer zugewiesen ist, und die Nummer trägt sie ab dann.

## Den Voice-Eintrag finden, der eine Nummer routet

Eine Nummer mit Voice hat zwei Identifier. Die `id` auf `GET /v1/numbers` beginnt mit `nda_` bei einer dedizierten Nummer und `nal_` bei einer geteilten, und die Numbers-Operationen verwenden sie. Die Voice-Operationen, einschließlich derjenigen, die festlegt, wohin eingehende Anrufe gehen, verwenden den Voice-Eintrag der Nummer, dessen `id` mit `vnu_` beginnt. Die Übergabe einer `nda_`- oder `nal_`-ID an eine Voice-Operation wird mit `422` abgelehnt.

Um von einem zum anderen zu gelangen, suchen Sie die Voice-Nummern anhand der Telefonnummer. Das erfordert den Scope `voice_management` auf Lesestufe:

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

Die `id` des Eintrags ist der `vnu_`-Identifier, und seine `provider.number_id` ist der `nda_`- oder `nal_`-Identifier derselben Nummer. [Anrufe empfangen](/docs/guides/voice/receiving-calls) zeigt, wie Sie die Nummer von dort aus routen.

Der Voice-Eintrag hat eine eigene `name`. Eine Nummer mit `PATCH /v1/numbers/{number_id}` zu benennen, lässt den Namen des Voice-Eintrags unverändert, und umgekehrt gilt dasselbe.

## Eine Nummer freigeben

Sie können eine dedizierte Nummer auf zwei Wegen zurückgeben:

- **Am Ende des bezahlten Zeitraums.** [`DELETE /v1/numbers/{number_id}`](/docs/api/reference/cancel-workspace-number) stoppt die Verlängerung der Nummer. Sie funktioniert bis zum Ende des aktuellen Abrechnungszeitraums weiter und wird dann freigegeben. Die `202`-Antwort gibt die Nummer mit `releases_at` auf diesen Zeitpunkt gesetzt zurück, und eine erneute Anfrage liefert dasselbe `releases_at`. Eine Kündigung kann nicht rückgängig gemacht werden. Eine Nummer ohne Abonnement, etwa eine ohne Gebühr zugewiesene, wird sofort freigegeben, und die Antwort ist `200` mit `status` der Nummer auf `released` gesetzt.
- **Sofort.** [`POST /v1/numbers/{number_id}/release`](/docs/api/reference/release-workspace-number) gibt die Nummer sofort frei, auch eine bereits zur Kündigung vorgemerkte. Der Rest des aktuellen Zeitraums wird nicht erstattet. [Eine Nummer kaufen und freigeben](/docs/guides/numbers/buying-numbers#release-a-number) zeigt den Aufruf in jedem SDK.

Solange eine Verlängerungszahlung für die Nummer überfällig ist, antworten beide Anfragen mit `409`, bis sie beglichen ist.

Unabhängig davon, welche Freigabeoption Sie wählen, senden Sie die Anfrage mit einem `Idempotency-Key`, damit ein erneuter Versuch sicher ist: Derselbe Schlüssel liefert die erste Antwort mit einem `Idempotency-Replay: true`-Header erneut, während eine neue Anfrage für eine bereits freigegebene Nummer mit `404` und [`E01008`](/docs/api/errors/E01008) antwortet. [Idempotenz](/docs/guides/idempotency) erklärt, wie lange ein Schlüssel aufbewahrt wird.

Bis eine geplante Kündigung wirksam wird, ist die Nummer wie gewohnt abrufbar und trägt `releases_at`. Nach der Freigabe:

- Die Nummer funktioniert nicht mehr für Sie, und ihr Abonnement verlängert sich nicht.
- `GET /v1/numbers/{number_id}` und der Voice-Eintrag der Nummer antworten mit `404`, und die Nummer verschwindet aus `GET /v1/numbers`.
- Die Bestellung der Nummer bleibt in [`GET /v1/numbers/orders`](/docs/api/reference/list-numbers-orders) erhalten, und ihr `number_id` antwortet jetzt mit `404`.
- Die Nummer geht in eine 30-tägige Sperrfrist, bevor sie wieder zum Verkauf stehen kann. Sie können dieselbe Nummer also nicht sofort erneut kaufen.

## Nächste Schritte

- [Anrufe empfangen](/docs/guides/voice/receiving-calls) leitet eine Nummer an einen SIP-Trunk, eine Weiterleitung oder eine Sequenz weiter.
- [Eine Nummer kaufen und freigeben](/docs/guides/numbers/buying-numbers) führt den Kauf über die API durch.
- [Numbers-API-Referenz](/docs/api/reference/list-workspace-numbers) dokumentiert jede Operation und jedes Feld.

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