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 in het dashboard toont dezelfde nummers.

Alle nummers opvragen die je hebt

GET /v1/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:

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

for allocated in client.numbers.list(country_code="GB"):
    print(allocated.number, allocated.kind, allocated.status)

for allocated, err := range client.Numbers.List(context.Background(), bird.NumbersListParams{
	CountryCode: "GB",
}) {
	if err != nil {
		log.Fatal(err)
	}
	fmt.Println(allocated.Number, allocated.Kind, allocated.Status)
}

$page = $bird->numbers->list(['country_code' => 'GB']);
foreach ($page as $allocated) {
    echo $allocated->getNumber(), ' ', $allocated->getKind(), ' ', $allocated->getStatus(), "\n";
}

curl "https://us1.platform.bird.com/v1/numbers?country_code=GB" \
  -H "Authorization: Bearer bk_us1_..."

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.

Elk item bevat zijn status en ownership. Wanneer een land geen eigendomsdocumenten vereist, is ownership gelijk aan null. Het Numbers-overzicht legt uit wat elke status betekent. Zie De eigendomsdocumenten van een nummer indienen 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_periods 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 om er een prijs voor te laten vaststellen. Als het tarief niet kon worden gelezen, bevat pricing.error de waarde E14009 en zijn de prijzen null. Probeer GET /v1/numbers/{number_id} 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:

Codevoorbeeld

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:

Codevoorbeeld

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

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

allocated = client.numbers.update(
    "nda_01krdgeqcxet5s7t44vh8rt9mg", name="Support line", reference="STORE-042"
)
print(allocated.name, allocated.reference)

allocated, err := client.Numbers.Update(ctx, "nda_01krdgeqcxet5s7t44vh8rt9mg", bird.NumbersUpdateParams{
	Name:      bird.Value("Support line"),
	Reference: bird.Value("STORE-042"),
})
if err != nil {
	log.Fatal(err)
}
if allocated.Name != nil {
	fmt.Println(*allocated.Name)
}
if allocated.Reference != nil {
	fmt.Println(*allocated.Reference)
}

$allocated = $bird->numbers->update(
    'nda_01krdgeqcxet5s7t44vh8rt9mg',
    (new \MessageBird\Wire\Model\NumberUpdate())->setName('Support line')->setReference('STORE-042'),
);
echo $allocated->getName(), ' ', $allocated->getReference(), "\n";

curl -X PATCH "https://{region}.platform.bird.com/v1/numbers/{number_id}" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Support line",
    "reference": "STORE-042"
  }'

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:

Codevoorbeeld

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

Codevoorbeeld

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 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} 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 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 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. 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 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 routeert een nummer naar een SIP-trunk, een doorschakeling of een reeks.
Een nummer kopen en vrijgeven doorloopt de aankoop via de API.
Numbers API-referentie documenteert elke operatie en elk veld.

Ga verder met de documentatie, handleidingen en voorbeelden voor dit onderwerp.

Ontvang een implementatieoverzicht

Je telefoonnummers beheren

Alle nummers opvragen die je hebt

Een nummer zoeken in je lijst

Een nummer benoemen en je referentie instellen

Het voice-record vinden dat een nummer routeert

Een nummer vrijgeven

Vervolgstappen

Gerelateerde bronnen