Rechercher un numéro de téléphone

Un seul appel répond à ce qu'est un numéro. Tout ce qui suit nécessite une clé API avec le scope lookup.

Lancer une recherche de base

Envoyez le numéro sans rien d'autre. La recherche de base est toujours facturée une fois, et elle renvoie toujours le pays, le réseau de desserte, le réseau d'attribution et un type de ligne approximatif.

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

answer = client.lookup.phone_number(
    phone_number="+31612345678", type=["classification", "score"]
)
print(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 is not None and answer.score.status == "ok":
    print(answer.score.value)

answer, err := client.Lookup.PhoneNumber(context.Background(), bird.LookupPhoneNumberParams{
	PhoneNumber: "+31612345678",
	Type:        []bird.LookupProperty{"classification", "score"},
})
if err != nil {
	log.Fatal(err)
}
fmt.Println(*answer.CountryCode, *answer.LineType)
// Only a block whose status is ok carries a value, and only that one is billed.
if answer.Score != nil && *answer.Score.Status == "ok" {
	fmt.Println(*answer.Score.Value)
}

$answer = $bird->lookup->phoneNumber(
    (new PhoneNumberLookupRequest())
        ->setPhoneNumber('+31612345678')
        ->setType(['classification', 'score']),
);
echo $answer->getCountryCode(), ' ', $answer->getLineType();
// Only a block whose status is ok carries a value, and only that one is billed.
if ($answer->getScore()?->getStatus() === 'ok') {
    echo $answer->getScore()->getValue();
}

bird lookup phone-number \
  --phone-number +31612345678 \
  --type classification \
  --type presence

curl -X POST "https://us1.platform.bird.com/v1/lookup/phone-number" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "phone_number": "+31612345678",
    "type": [
      "classification",
      "presence"
    ]
  }'

Comment écrire le numéro

Envoyez l'indicatif téléphonique du pays, puis le numéro national. Le + initial est facultatif et 00 fonctionne à sa place, donc +31612345678, 31612345678 et 0031612345678 désignent tous le même numéro.

Un numéro écrit pour un appel national, sans indicatif pays, est rejeté plutôt que deviné. 0612345678 renvoie E22000, car ajouter un indicatif pays désignerait un vrai numéro ailleurs et vous serait facturé.

Ce que la recherche de base renvoie

country_code est le pays du numéro, absent lorsque le numéro n'appartient à aucun pays en particulier, comme c'est le cas pour une plage non géographique.

network_info est le réseau qui dessert le numéro aujourd'hui, et original_network_info est le réseau qui a attribué sa plage. Les deux diffèrent lorsque le numéro a été porté, et dans ce cas flags contient ported.

line_type indique le type de ligne du numéro : mobile, fixed_line, voip, toll_free, premium_rate, satellite, pager, payphone, m2m, service, other ou unknown. unknown signifie que la plateforme opérateur ne possède aucune classification pour la plage ; other signifie qu'elle en possède une sans équivalent ici. Pour le service alloué avec une précision plus fine, demandez la propriété classification. Elle interroge une source différente avec un vocabulaire plus large, et elle est rapportée séparément pour que vous puissiez toujours distinguer les deux.

Ajouter des propriétés

Nommez les propriétés souhaitées dans type. Chacune est facturée séparément et uniquement lorsqu'elle est livrée.

classification, porting et score lisent des données stockées et répondent rapidement. presence, roaming et sim_swap interrogent le réseau en temps réel, donc ils sont plus lents et leur couverture varie selon l'opérateur. Attendez-vous à recevoir unavailable ou inconclusive plus souvent pour ceux-ci que pour les propriétés stockées.

Deux propriétés répondent à des questions que la recherche de base aborde déjà, avec une résolution plus fine. porting vous donne la date et l'historique complet là où le flag ported de la recherche de base indique seulement si un portage a eu lieu. classification résout line_type vers le service alloué exact.

Lire le statut avant la valeur

Chaque bloc de propriété porte un status, et seul ok contient une valeur.

{
  "phone_number": "+441904123456",
  "country_code": "GB",
  "line_type": "service",
  "classification": {
    "status": "ok",
    "value": "premium_rate"
  },
  "score": {
    "status": "unavailable"
  }
}

Dans cette réponse, la recherche de base et classification vous ont été facturés. score ne vous a pas été facturé.

Lisez status en premier et traitez toute valeur autre que ok comme "not answered". C'est un vocabulaire ouvert : une valeur que vous ne reconnaissez pas est un statut futur, pas une erreur.

Deux blocs rapportent une borne plutôt qu'une valeur exacte lorsque le réseau ne la communique pas. sim_swap renvoie min_days et max_days au lieu de last_swapped_at lorsque seule une plage de récence est connue. porting définit last_ported_at_is_approximate lorsqu'un registre enregistre la période d'un portage mais pas son jour exact.

Un champ se lit comme un résultat négatif mais constitue un résultat positif : porting.ported défini à false signifie que le registre a été consulté et ne contient aucun portage pour ce numéro, et non que rien n'a pu être vérifié. C'est à cela que sert status.

Réessayer sans payer deux fois

Une recherche est facturée, donc une requête réessayée ne doit pas acheter une deuxième réponse. Envoyez un Idempotency-Key et la répétition de la même requête rejoue la réponse stockée au lieu de lancer une nouvelle recherche. Voir Idempotency.

La forme GET de cette opération, qui place le numéro dans l'URL, ne peut pas porter de clé d'idempotence. Utilisez la forme POST pour tout traitement automatisé.

Erreurs

Une propriété en échec n'est pas une erreur. Elle revient sous forme de statut sur son bloc, et la recherche de base est servie à côté.

Étapes suivantes

• Rechercher une adresse e-mail est l'autre volet de Lookup.
• Référence API de Lookup documente chaque champ et chaque bloc de propriété.
• Limites de débit couvre le bucket lookup utilisé par ces appels.
• Recherche de numéro de téléphone : vérifiez un numéro avant d'envoyer est une vidéo qui exécute une recherche et ajoute les vérifications réseau en temps réel.