---
title: "Je telefoonnummers beheren"
description: "Bekijk en zoek de nummers die aan je werkruimte zijn toegewezen, geef ze een naam en je eigen referentie, zoek hun voice-record op, en annuleer of geef ze vrij via de API."
canonical: "https://bird.com/nl-nl/documentatie/guides/numbers/managing-numbers"
---

# Je telefoonnummers beheren

Zodra een nummer aan je werkruimte is toegewezen, kun je met de numbers-API bekijken wat je hebt, één nummer zoeken op elk van zijn identificatoren, het voorzien van een naam en je eigen referentie, en het annuleren of vrijgeven wanneer je klaar bent. Lezen vereist een API-sleutel met het `numbers`-bereik op leesniveau; wijzigen, annuleren of vrijgeven vereist schrijfniveau.

De pagina [**Numbers**](https://bird.com/dashboard/w/numbers) in het dashboard toont dezelfde nummers.

## Alle nummers opvragen die je hebt

[`GET /v1/numbers`](/docs/api/reference/list-workspace-numbers) geeft de nummers terug die momenteel aan je werkruimte zijn toegewezen, nieuwste eerst, zowel dedicated als gedeeld. Elke pagina bevat 25 nummers, tenzij je er tot 100 opvraagt met `limit`.

De lijst wordt per cursor gepagineerd. Geef de `next_cursor` van een pagina door als `starting_after` om de volgende pagina te lezen, en stop wanneer `next_cursor` gelijk is aan `null`. De SDK's volgen de cursor automatisch. De voorbeelden hieronder beperken de lijst tot `country_code: "GB"`; laat het filter weg om al je nummers te doorlopen:

**TypeScript**

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

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

Gebruik de regionale host die overeenkomt met het `bk_{region}_`-prefix van je sleutel: `https://us1.platform.bird.com` of `https://eu1.platform.bird.com`.

De lijst bevat geen totaal. Om je nummers te tellen, doorloop je de pagina's tot het einde en tel je de items. Het meegeven van `include_total` wordt geweigerd met `422` en [`E01029`](/docs/api/errors/E01029).

Elk item bevat zijn `status` en `ownership`. Wanneer een land geen eigendomsdocumenten vereist, is `ownership` gelijk aan `null`. Het [Numbers-overzicht](/docs/guides/numbers/overview#the-status-of-an-allocated-number) legt uit wat elke status betekent. Zie [De eigendomsdocumenten van een nummer indienen](/docs/guides/numbers/ownership-paperwork) om de documenten in te dienen waarop een nummer wacht.

Elk item bevat ook `pricing`, wat je organisatie voor het nummer betaalt, exclusief belasting:

- `recurring_price` is je tarief per `recurring_period`, in de valuta waarin het nummer wordt gefactureerd. Dat is je factureringsvaluta, tenzij het abonnement van het nummer begon voordat je factureringsvaluta veranderde; zo'n nummer behoudt de valuta van zijn abonnement, die `currency_code` vermeldt.
- `intervals_per_charge` is het aantal `recurring_period`s dat één verlenging in rekening brengt. De periodieke kosten vóór belasting zijn `recurring_price` vermenigvuldigd met `intervals_per_charge`. Een vast tarief voor het nummer dekt de hele periode, dus `intervals_per_charge` is `1`.

`pricing` is `null` voor een `shared`-nummer en voor een nummer zonder actief abonnement. Als er voor het abonnement van een nummer geen tarief van toepassing is, zijn de prijzen `null` met `pricing.error: null`; [neem contact op met sales](/contact-sales) om er een prijs voor te laten vaststellen. Als het tarief niet kon worden gelezen, bevat `pricing.error` de waarde [`E14009`](/docs/api/errors/E14009) en zijn de prijzen `null`. Probeer [`GET /v1/numbers/{number_id}`](/docs/api/reference/get-workspace-number) opnieuw met exponentiële backoff. Het nummer blijft beschikbaar om te beheren; herhaal een voltooide update of annulering niet om de prijs te vernieuwen.

Het dashboard en API gebruiken dezelfde prijsbepaling. Een vaste prijs behoudt de bestaande voorwaarden; anders is het het huidige tarief, dat vóór verlenging kan wijzigen. Het toont niet wat een eerdere bestelling in rekening heeft gebracht. Een nummer waarvoor `releases_at` is ingesteld, behoudt zijn `pricing` tot de vrijgave, en er volgt geen verlenging.

## Een nummer zoeken in je lijst

De lijstfilters worden gecombineerd, dus een land- of capaciteitsfilter blijft ook naast de andere filters van toepassing.

`number` zoekt één nummer op, ongeacht hoe je administratie het noteert. `+31612345678` en `0031612345678` verwijzen naar hetzelfde nummer. Een nationale notatie zoals `0612345678` werkt alleen als `country_code` het land vermeldt:

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

Wanneer je een volledig nummer doorgeeft, of een nationale notatie met het bijbehorende `country_code`, zonder ander filter, betekent een lege `data`-array dat het nummer niet aan je werkruimte is toegewezen, inclusief een nummer dat je hebt vrijgegeven. Een nationale notatie zonder `country_code`, zoals `0612345678` alleen, geeft ook een lege lijst terug en bewijst dus niet dat het nummer niet van jou is.

`search` zoekt in een deel van het nummer, de naam of de referentie, zonder onderscheid tussen hoofd- en kleine letters. `reference` geeft de nummers terug met exact die referentie, met onderscheid tussen hoofd- en kleine letters:

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

`prefix` geeft nummers terug die beginnen met de cijfers die je opgeeft, en de betekenis van die cijfers hangt af van `country_code`:

- Met `country_code` zijn de cijfers nationale cijfers, gematcht direct na de landcode. `prefix=6&country_code=NL` geeft Nederlandse nummers terug die beginnen met `+31 6`.
- Zonder `country_code` worden de cijfers gematcht vanaf het begin van het volledige nummer. `prefix=6` alleen geeft nummers terug waarvan de landcode begint met 6, zoals Australische `+61`-nummers, en vindt dus geen van je Nederlandse mobiele nummers. Het matcht ook shortcodes die met die cijfers beginnen.

## Een nummer benoemen en je referentie instellen

Een nummer heeft twee eigen labels. `name` onderscheidt je nummers, zoals `Support line`. `reference` bevat een identifier uit je eigen administratie, zoals een klant- of winkel-id, en hoeft niet uniek te zijn. Beide gelden voor dedicated en gedeelde nummers en zijn maximaal 100 tekens.

Stel ze in met [`PATCH /v1/numbers/{number_id}`](/docs/api/reference/update-workspace-number). Een veld dat je weglaat behoudt de huidige waarde, en een veld dat je als `null` verstuurt wordt gewist. Witruimte aan het begin en einde wordt verwijderd.

**TypeScript**

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

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

Het antwoord is `200` met het bijgewerkte nummer. Om de referentie te wissen en de naam te behouden, stuur je de referentie als `null` en laat je de naam 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}'
```

Om de referentie in te stellen wanneer je het nummer koopt, geef je `reference` mee aan [`POST /v1/numbers/orders`](/docs/api/reference/create-numbers-order). Een bestelling die op een provider moet wachten, bewaart de referentie totdat het nummer is toegewezen, en het nummer draagt deze vanaf dat moment mee.

## Het voice-record vinden dat een nummer routeert

Een nummer met voice heeft twee identifiers. De `id` op `GET /v1/numbers` begint met `nda_` voor een dedicated nummer en `nal_` voor een gedeeld nummer, en de nummerbewerkingen gebruiken deze. De voice-bewerkingen, waaronder die waarmee je instelt waar inkomende oproepen naartoe gaan, gebruiken het voice-record van het nummer, waarvan de `id` begint met `vnu_`. Een `nda_`- of `nal_`-id meegeven aan een voice-bewerking wordt geweigerd met `422`.

Om van het ene naar het andere te komen, zoek je de voice-nummers op telefoonnummer. Dit vereist het `voice_management`-bereik op leesniveau:

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

De `id` van het item is de `vnu_`-identifier, en de `provider.number_id` is de `nda_`- of `nal_`-identifier van hetzelfde nummer. [Oproepen ontvangen](/docs/guides/voice/receiving-calls) laat zien hoe je het nummer van daaruit routeert.

Het voice-record heeft een eigen `name`. Een nummer een naam geven met `PATCH /v1/numbers/{number_id}` wijzigt de naam van het voice-record niet, en andersom geldt hetzelfde.

## Een nummer vrijgeven

Je kunt een dedicated nummer op twee manieren teruggeven:

- **Aan het einde van de periode waarvoor je hebt betaald.** [`DELETE /v1/numbers/{number_id}`](/docs/api/reference/cancel-workspace-number) stopt de verlenging van het nummer. Het blijft werken tot de huidige factureringsperiode afloopt en wordt dan vrijgegeven. Het `202`-antwoord retourneert het nummer met `releases_at` ingesteld op dat tijdstip, en opnieuw aanvragen retourneert dezelfde `releases_at`. Een annulering kan niet ongedaan worden gemaakt. Een nummer zonder onderliggend abonnement, zoals een nummer dat je zonder kosten is toegewezen, wordt direct vrijgegeven, en het antwoord is `200` met de `status` van het nummer ingesteld op `released`.
- **Nu.** [`POST /v1/numbers/{number_id}/release`](/docs/api/reference/release-workspace-number) geeft het nummer onmiddellijk vrij, ook als er al een annulering gepland is. De rest van de huidige periode wordt niet terugbetaald. [Een nummer kopen en vrijgeven](/docs/guides/numbers/buying-numbers#release-a-number) toont de aanroep in elke SDK.

Zolang een verlengingsbetaling voor het nummer achterstallig is, beantwoorden beide verzoeken met `409`, totdat de betaling is voldaan.

Welke vrijgaveoptie je ook kiest, stuur het verzoek met een `Idempotency-Key`, zodat een nieuwe poging veilig is: dezelfde sleutel speelt het eerste antwoord opnieuw af met een `Idempotency-Replay: true`-header, terwijl een nieuw verzoek voor een al vrijgegeven nummer `404` beantwoordt met [`E01008`](/docs/api/errors/E01008). [Idempotency](/docs/guides/idempotency) legt uit hoe lang een sleutel bewaard blijft.

Zolang een geplande annulering niet is ingegaan, is het nummer gewoon leesbaar en bevat het `releases_at`. Na de vrijgave:

- Het nummer werkt niet meer voor je en het abonnement wordt niet verlengd.
- `GET /v1/numbers/{number_id}` en het voice-record van het nummer beantwoorden `404`, en het nummer verdwijnt uit `GET /v1/numbers`.
- De bestelling van het nummer blijft in [`GET /v1/numbers/orders`](/docs/api/reference/list-numbers-orders) staan, en zijn `number_id` beantwoordt nu `404`.
- Het nummer gaat 30 dagen in een afkoelperiode voordat het weer in de verkoop kan komen, dus je kunt hetzelfde nummer niet direct terugkopen.

## Vervolgstappen

- [Oproepen ontvangen](/docs/guides/voice/receiving-calls) routeert een nummer naar een SIP-trunk, een doorschakeling of een reeks.
- [Een nummer kopen en vrijgeven](/docs/guides/numbers/buying-numbers) doorloopt de aankoop via de API.
- [Numbers API-referentie](/docs/api/reference/list-workspace-numbers) documenteert elke operatie en elk veld.

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