FAQ Lookup API

Lookup répond à des questions sur un destinataire avant que vous ne lui envoyiez un message. Donnez-lui un numéro de téléphone et il vous indique ce qu'est ce numéro : le réseau qui le dessert, le pays, s'il a changé de réseau, et le type de ligne. Donnez-lui une adresse e-mail et il vous dit si cette adresse vaut la peine d'être contactée.

Deux choses, une opération chacune. Une recherche de numéro de téléphone renvoie le pays, le réseau desservant le numéro, le réseau qui l'a attribué, s'il a migré entre les deux, et le type de ligne, plus toute propriété que vous demandez. Une recherche d'adresse e-mail renvoie un verdict, un score de confiance et les flags associés.

Chaque recherche se résume à une requête et une réponse. Rien à créer, rien à interroger périodiquement, rien à nettoyer ensuite. Des méthodes typées sont disponibles dans les SDK Go, TypeScript, Python et PHP, et bird lookup phone-number ainsi que bird lookup email font la même chose depuis la CLI.

Oui. La page Lookup dans le tableau de bord exécute les deux mêmes opérations une à la fois, ce qui est le moyen le plus rapide de voir à quoi ressemble une réponse avant de construire dessus.

Une clé API avec le scope lookup, et un portefeuille d'organisation pouvant couvrir le coût. La tarification est par requête sans frais par utilisateur, il n'y a donc pas de plan à choisir au préalable.

Utilisez-le quand vous voulez décider avant de vous engager : filtrer une inscription, vérifier un prospect avant d'agir, ou router un message différemment selon le type de ligne. Vous obtenez une réponse exploitable sans rien envoyer au préalable.

Par requête. Chaque recherche est facturée sur le portefeuille de votre organisation. Une recherche de numéro de téléphone est facturée une fois pour la recherche de base, plus un frais pour chaque propriété qui revient avec une réponse. Une recherche d'adresse e-mail est facturée une fois par adresse ayant obtenu une réponse. Il n'y a pas de frais par utilisateur.

La page de tarification Lookup indique le tarif pour la recherche de base, pour chaque propriété et pour une recherche d'adresse e-mail. Les tarifs varient selon la propriété, car chacune provient d'une source de données différente.

Non. Une propriété n'est facturée que lorsqu'elle est effectivement renvoyée. Une propriété sans réponse revient avec un statut l'indiquant et ne vous coûte rien, et la recherche de base est tout de même servie en parallèle.

Rien n'est facturé. Un numéro mal formaté, une adresse que nous refusons et une source de données injoignable ne coûtent rien.

Oui. Chaque adresse ayant obtenu une réponse est facturée, y compris les non distribuables. C'est la réponse que vous avez demandée, et c'est celle qui vous évite un rebond.

Pas si vous envoyez un Idempotency-Key. Une répétition de la même requête renvoie la réponse enregistrée au lieu d'exécuter une nouvelle recherche. Les formes GET, qui placent le numéro ou l'adresse dans l'URL, ne peuvent pas porter de clé d'idempotence, utilisez donc POST pour tout ce qui est automatisé.

La limite de débit des recherches commence à 10 requêtes par minute, comptées par identifiant actif, de sorte qu'une clé très sollicitée ne peut pas bloquer les autres. Chaque recherche interroge une source de données externe et débite votre portefeuille pour la réponse, c'est pourquoi elle commence au même niveau que les limites d'envoi.

Pas aujourd'hui. Aucune des deux opérations ne dispose d'un mode par lot, ce service n'est donc pas dimensionné pour vérifier une liste entière. Demandez-nous de relever la limite si c'est ce dont vous avez besoin, plutôt que de contourner cette restriction.

Le scope lookup au niveau écriture. Il n'a pas de niveau lecture : chaque endpoint de recherche nécessite le niveau écriture, y compris pour récupérer un résultat déjà payé. Les propriétaires et administrateurs le possèdent par défaut, les membres non.

Quatre qui comptent. E22000 lorsque le numéro n'est pas valide au format international, E22003 lorsque l'adresse n'est pas une adresse e-mail valide, E22001 lorsque le portefeuille de l'organisation ne peut pas couvrir la recherche, et E22002 lorsque Lookup est temporairement indisponible. Aucune ne vous est facturée.

Non. Une propriété en échec est renvoyée avec un statut dans son propre bloc, la recherche de base étant servie à côté. Seul l'échec de la recherche de base fait échouer la requête, et dans ce cas elle échoue complètement plutôt que de renvoyer une réponse à moitié vide que vous devriez inspecter pour découvrir qu'elle est vide.

La recherche de base renvoie le pays du numéro, le réseau qui le dessert actuellement, le réseau qui a attribué sa plage, s'il a déjà changé de réseau, et un type de ligne approximatif. Elle s'exécute systématiquement, et si elle ne peut pas aboutir, la requête entière échoue plutôt que de renvoyer une réponse à moitié vide.

L'indicatif international d'abord, puis le numéro national. Le plus 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, renvoie E22000 au lieu d'être deviné. Ajouter un indicatif pays devant 0612345678 désignerait un vrai numéro ailleurs et vous facturerait la recherche de celui-ci à la place.

mobile, fixed_line, voip, toll_free, premium_rate, satellite, pager, payphone, m2m, service, other ou unknown. unknown signifie que la plateforme de l'opérateur ne détient aucune classification pour la plage, et other signifie qu'elle en détient une sans équivalent ici. Demandez la propriété classification pour connaître le service alloué avec une précision plus fine.

network_info est le réseau qui dessert le numéro actuellement et original_network_info est le réseau qui a attribué sa plage. Les deux diffèrent une fois le numéro porté, et flags contient ported dans ce cas. Demandez la propriété porting lorsque vous avez aussi besoin de la date et de l'historique complet.

Parce que le numéro n'appartient à aucun pays en particulier, comme c'est le cas pour une plage non géographique. Les champs sans valeur sont omis plutôt que renvoyés comme null, donc chaque champ présent dans la réponse a bien été résolu.

Non. Une recherche ne contacte jamais le numéro lui-même. Elle lit les données de l'opérateur et d'intelligence numérique, et les propriétés presence et roaming interrogent le réseau sur lequel le numéro est enregistré, donc rien ne sonne et rien n'arrive sur le terminal.

Six, nommées dans type. classification pour le service alloué précis de la plage, porting pour la date du dernier changement de réseau et l'historique complet, presence pour savoir s'il est actif sur le réseau en ce moment, roaming pour savoir s'il est en itinérance et sur quel réseau, sim_swap pour la date du dernier changement de SIM, et score pour un score de crédibilité de 0 à 100.

Oui. classification, porting et score lisent des données enregistrées et répondent rapidement. presence, roaming et sim_swap interrogent le réseau en temps réel, elles sont donc plus lentes et leur couverture varie selon l'opérateur. Attendez-vous à recevoir unavailable ou inconclusive plus souvent pour ces trois propriétés que pour celles basées sur des données enregistrées.

ok signifie que la propriété a reçu une réponse, que sa valeur figure dans la réponse et qu'elle a été facturée. unavailable signifie qu'aucune réponse n'est arrivée et qu'elle n'a pas été facturée. inconclusive signifie qu'une réponse est arrivée mais ne résout pas la propriété, ce qui est un résultat réel, et elle n'a pas été facturée non plus.

Oui, status est un vocabulaire ouvert. Branchez votre logique sur ok et traitez tout le reste comme non résolu, et votre code restera correct quelle que soit l'évolution du vocabulaire.

porting vous donne la date et l'historique complet, là où le flag ported de la recherche de base indique seulement si un transfert a eu lieu. classification résout line_type vers le service alloué exact, à partir d'une source différente avec un vocabulaire plus large, et est rapporté séparément pour que vous puissiez toujours distinguer les deux.

Parce que le réseau n'a pas communiqué de valeur exacte. sim_swap renvoie min_days et max_days au lieu de last_swapped_at lorsque seule une fourchette de récence est connue. porting fait quelque chose de similaire : il définit last_ported_at_is_approximate lorsqu'un registre enregistre la période d'un transfert mais pas le jour exact.

Non. Cela signifie que le registre a été consulté et ne contient aucun transfert pour ce numéro, ce qui est un résultat concernant le numéro et non une lacune dans la réponse. C'est le status du bloc qui vous indique si la vérification a été exécutée ou non.

Comme un signal parmi d'autres. Il va de 0 pour une crédibilité faible à 100 pour une crédibilité élevée, c'est un score composite, et vous ne pouvez pas le déduire des autres propriétés. Évaluez-le en regard du reste de la réponse au lieu de vous fier uniquement à lui.

Si l'adresse accepte le courrier. Un seul appel renvoie un verdict dans result, un score delivery_confidence, les flags qui décrivent le type d'adresse, et une correction lorsque l'adresse ressemble à une faute de frappe.

valid signifie que l'adresse existe et accepte le courrier : envoyez. neutral signifie qu'il n'a pas été possible de confirmer dans un sens ou dans l'autre, généralement parce que le domaine destinataire répond de la même manière pour tous les destinataires. risky signifie que l'adresse accepte probablement le courrier mais qu'elle a plus de chances que la moyenne de rebondir ou de générer une plainte. undeliverable signifie qu'elle n'accepte pas le courrier. typo signifie que l'adresse semble mal orthographiée.

reason indique lequel des trois problèmes est en cause : invalid_syntax pour une adresse mal formée, invalid_domain lorsque le domaine n'accepte aucun courrier, et invalid_recipient lorsque le domaine accepte le courrier mais que cette boîte aux lettres n'existe pas.

Proposez did_you_mean à la personne qui a saisi l'adresse originale plutôt que d'envoyer directement à cette adresse. La correction est une suggestion, et l'adresse voulue peut ne correspondre ni à l'une ni à l'autre.

Il va de 0, certitude de non-livraison, à 100, certitude de livraison. Un même score peut se trouver sous différents verdicts pour différentes raisons : lisez-le en complément de result, et non à sa place. C'est le champ à privilégier lorsque vous souhaitez un seuil unique pour tous les verdicts, y compris ceux ajoutés ultérieurement.

Non, et la différence est importante. Le champ valid est plus restrictif : il indique si l'adresse est bien formée et si son domaine est configuré pour recevoir du courrier. Il ne dit rien sur la boîte aux lettres : une adresse avec un domaine fonctionnel mais sans boîte aux lettres correspondante sera true pour ce champ et undeliverable dans result.

role signifie que l'adresse désigne une fonction plutôt qu'une personne, comme support@ ou info@ : les réponses et le consentement sont ambigus et les plaintes plus probables. disposable signifie un fournisseur d'adresses jetables : l'adresse cessera généralement d'exister. free_provider signifie un fournisseur de messagerie grand public comme Gmail ou Outlook.com, ce qui n'est un signal que lorsque vous attendiez une adresse professionnelle.

Envoyez une adresse brute, exactement telle que vous la détenez. Un format avec nom d'affichage, avec un nom devant et l'adresse entre chevrons, est rejeté plutôt que décomposé, car le décomposer reviendrait à rechercher une adresse que vous n'avez pas envoyée. La partie avant l'arobase est transmise telle quelle, et modifier sa casse peut changer le delivery_confidence obtenu.

Non. Les suppressions s'en chargent automatiquement et gratuitement, pour les adresses qui ont déjà rebondi ou généré une plainte. Utilisez Lookup pour les adresses auxquelles vous n'avez pas encore envoyé, à l'inscription ou avant d'exploiter un prospect.