Sign inGet Started

Een telefoonnummer opzoeken

Eén aanroep beantwoordt wat een nummer is. Alles hier vereist een API-sleutel met het lookup-bereik.

Een basiszoekopdracht uitvoeren

Stuur het nummer en niets anders. De basiszoekopdracht wordt altijd één keer gefactureerd en beantwoordt altijd het land, het bedienende netwerk, het uitgevende netwerk en een globaal lijntype.
const answer = await bird.lookup.phoneNumber({
  phone_number: "+31612345678",
  type: ["classification", "score"],
});
console.log(answer.country_code, answer.line_type);
// Only a block whose status is ok carries a value, and only that one is billed.
if (answer.score?.status === "ok") console.log(answer.score.value);

Hoe je het nummer schrijft

Stuur de landcode en dan het nationale nummer. De voorloop-+ is optioneel en 00 werkt ook, dus +31612345678, 31612345678 en 0031612345678 zijn allemaal hetzelfde nummer.
Een nummer dat is geschreven om binnen één land te bellen, zonder landcode, wordt geweigerd in plaats van geraden. 0612345678 retourneert E22000, omdat het toevoegen van een landcode een bestaand nummer ergens anders zou aanduiden en je gefactureerd zou worden voor het opzoeken ervan.

Wat de basisopzoeking beantwoordt

country_code is het land van het nummer, afwezig wanneer het nummer niet tot één land behoort, zoals bij een niet-geografisch nummerbereik.
network_info is het netwerk dat het nummer nu bedient, en original_network_info is het netwerk dat het bereik heeft uitgegeven. De twee verschillen wanneer het nummer is geporteerd, en in dat geval bevat flags de waarde ported.
line_type is het type lijn van het nummer: mobile, fixed_line, voip, toll_free, premium_rate, satellite, pager, payphone, m2m, service, other of unknown. unknown betekent dat het carrierplatform geen classificatie heeft voor het bereik; other betekent dat het er wel een heeft zonder equivalent hier. Vraag voor de toegewezen dienst op fijnere precisie de property classification op. Die beantwoordt vanuit een andere bron met een bredere woordenschat en wordt apart gerapporteerd zodat je de twee altijd kunt onderscheiden.

Properties toevoegen

Geef de gewenste properties op in type. Elke property wordt apart gefactureerd en alleen als deze geleverd is.
PropertyWat het beantwoordt
classificationDe precieze toegewezen dienst van het bereik: premium rate, satelliet, M2M, telefooncel.
portingWanneer het nummer voor het laatst van netwerk is gewisseld, en elke wissel in het register.
presenceOf het nummer momenteel actief is op het netwerk.
roamingOf het nummer roamt, en op welk netwerk.
sim_swapWanneer de simkaart voor het laatst is gewisseld.
scoreEen geloofwaardigheidsscore van 0 tot 100.
classification, porting en score lezen opgeslagen data en antwoorden snel. presence, roaming en sim_swap benaderen het live netwerk, dus ze zijn trager en hun dekking verschilt per operator. Verwacht unavailable of inconclusive hierbij vaker dan bij de opgeslagen properties.
Twee properties beantwoorden vragen die de basisopzoeking al aanraakt, maar op hogere resolutie. porting geeft je de datum en de volledige geschiedenis, terwijl de ported-vlag van de basisopzoeking alleen aangeeft of er ooit een wissel heeft plaatsgevonden. classification vertaalt line_type naar de exacte toegewezen dienst.

Lees de status vóór de waarde

Elk propertyblok bevat een status, en alleen ok bevat een waarde.
Codevoorbeeld
{
  "phone_number": "+441904123456",
  "country_code": "GB",
  "line_type": "service",
  "classification": {
    "status": "ok",
    "value": "premium_rate"
  },
  "score": {
    "status": "unavailable"
  }
}
In dat antwoord is je de basisopzoeking en classification gefactureerd. score is je niet gefactureerd.
Lees status eerst en behandel alles anders dan ok als "not answered". Het is een open vocabulaire, dus een waarde die je niet herkent is een toekomstige status, geen fout.
Twee blokken rapporteren een grens in plaats van een exact getal wanneer het netwerk er geen vrijgeeft. sim_swap retourneert min_days en max_days in plaats van last_swapped_at wanneer alleen een recentheidsband bekend is. porting zet last_ported_at_is_approximate wanneer een register de periode van een wissel vastlegt maar niet de dag.
Eén veld leest als negatief maar is een positieve bevinding: porting.ported met waarde false betekent dat het register is geraadpleegd en geen wissel voor dit nummer bevat, niet dat er niets gecontroleerd kon worden. Dat onderscheid is waarvoor status dient.

Opnieuw proberen zonder dubbel te betalen

Een opzoeking wordt gefactureerd, dus een herhaald verzoek mag geen tweede antwoord kopen. Stuur een Idempotency-Key mee en een herhaling van hetzelfde verzoek speelt het opgeslagen antwoord af in plaats van een nieuwe opzoeking uit te voeren. Zie Idempotentie.
De GET-vorm van deze operatie, die het nummer in de URL plaatst, kan geen idempotentiesleutel meesturen. Gebruik de POST-vorm voor alles wat geautomatiseerd is.

Fouten

CodeWat er gebeurde
E22000Het nummer is geen geldig telefoonnummer in internationaal formaat. Er is niets in rekening gebracht.
E22001De wallet van de organisatie dekt de opzoeking niet. Laad deze op en probeer het opnieuw. Er is niets in rekening gebracht.
E22002Opzoeking is tijdelijk niet beschikbaar. Probeer opnieuw met backoff. Er is niets in rekening gebracht.
Een falende property is geen fout. Deze komt terug als status op het blok, terwijl de basisopzoeking gewoon meegeleverd wordt.

Volgende stappen

Gerelateerde bronnen

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