Questions & réponses
Lookup : vos questions, nos réponses.
Découvrez les vérifications adaptées aux contacts que vous devez vérifier.
Conçu avec BirdTémoignages clients
Témoignages clientsConçu avec Bird
La confiance des équipes d’ingénierie et produit qui livrent à l’échelle mondiale.
Questions fréquentesExplications
ExplicationsQuestions fréquentes
FAQ Lookup API
Qu'est-ce que Bird Lookup ?
Bird Lookup verifies phone numbers and email addresses before you send a message or accept a signup. For a phone number, it returns the country, serving and issuing carriers, porting status, line type, and optional network checks. For an email address, it returns a deliverability verdict, confidence score, inbox type flags, and suggested typo corrections.
Que puis-je rechercher ?
You can check phone numbers and email addresses through dedicated endpoints. A phone number lookup returns the country, serving carrier, original issuing carrier, porting status, and line type, along with any optional enrichment properties you request. An email address lookup validates a single address or a synchronous batch and returns a deliverability verdict, confidence score, and address classification flags.
Quel effort d'intégration cela demande-t-il ?
A lookup completes in a single synchronous request and response without webhook setup or polling. You can call the REST endpoints directly, use typed methods in the Go, TypeScript, Python, and PHP SDKs, or run phone number and email lookups from the terminal with the Bird CLI.
Puis-je effectuer une recherche sans écrire de code ?
Yes. You can check individual phone numbers and email addresses directly from the Lookup page in the Bird dashboard to inspect carrier details, enrichment properties, and deliverability verdicts before integrating the API.
De quoi ai-je besoin avant ma première recherche ?
You need an API key with lookup write permission and a funded organization wallet. Lookups are billed per query without monthly seat fees or upfront plan commitments.
Quand utiliser Lookup plutôt que d'envoyer directement ?
Use Lookup when you want to verify contact details before spending on delivery or admitting an account. Common workflows include blocking disposable emails and virtual numbers at signup, screening lead lists before outreach, and routing OTPs to voice instead of SMS when a number is a landline.
Comment Lookup est-il tarifé ?
Lookups are billed per query from your organization's wallet with no seat fees. A phone number lookup charges a base rate plus an individual fee for each requested enrichment property that returns an answer. An email address lookup charges per validated address.
Où trouver les tarifs ?
The Lookup pricing page lists the per-query rate for a base phone number lookup, each optional enrichment property, and an email address lookup. Property rates vary because each check queries a distinct carrier or intelligence data source.
Suis-je facturé pour une propriété qui revient vide ?
No. You are charged for an enrichment property when it returns a resolved answer. If a property is unavailable or inconclusive, its status explains why at no charge for that property, and you still receive the base phone number lookup.
Qu'advient-il de ma facturation quand une recherche échoue ?
Les requêtes échouées ne sont pas facturées. Si un numéro de téléphone ou une adresse e-mail individuelle est mal formé, ou si une source de données en amont est injoignable, votre portefeuille n’est pas débité. Un lot d’e-mails renvoie une évaluation pour chaque adresse et facture chacune d’elles, y compris les adresses mal formées.
Suis-je facturé pour une adresse qui s'avère non distribuable ?
Yes. Validated email addresses are billed regardless of the deliverability verdict, including undeliverable addresses. Identifying an invalid mailbox upfront prevents a hard bounce and protects your sender reputation.
Une nouvelle tentative peut-elle me facturer deux fois ?
Envoyez un en-tête Idempotency-Key avec une requête de recherche POST. Une nouvelle tentative avec la même clé et une requête identique, dans le même espace de travail et dans un délai de trois heures, renvoie la réponse enregistrée sans exécuter ni facturer une nouvelle recherche. Au-delà de trois heures, ou si aucune réponse n’a été conservée, par exemple pour une réponse de lot d’e-mails supérieure à 256 Kio, une nouvelle tentative peut exécuter et facturer à nouveau la recherche ou le lot. Les formes GET, qui placent le numéro ou l’adresse dans l’URL, n’acceptent pas de clés d’idempotence : utilisez donc les endpoints POST pour les workflows automatisés.
Combien de recherches puis-je effectuer par minute ?
Cela dépend de la limite de débit Lookup de votre organisation. Cette limite est partagée entre toutes les clés API et tous les espaces de travail de votre organisation : créer une nouvelle clé n’ajoute donc pas de capacité. Un lot d’e-mails de 1 000 adresses maximum compte comme une seule requête. Les en-têtes de limitation du débit des réponses Lookup indiquent la limite qui s’applique à votre requête. Chaque recherche interroge des sources de données externes d’opérateurs ou de domaines et est débitée de votre portefeuille : les nouvelles organisations commencent donc avec une limite prudente. Contactez-nous pour l’augmenter à mesure que votre volume croît, et consultez le guide Rate limits de la documentation pour savoir lire les en-têtes.
Existe-t-il une recherche par lot ou en masse ?
Email address lookup supports synchronous batches of up to 1,000 addresses in a single request, with a maximum request body of 128 KiB. Phone number lookup checks one number per request, and you can contact us to raise your rate limit for higher-throughput phone verification.
Quel scope faut-il pour une recherche ?
Lookup endpoints require the lookup permission scope with write access. Because lookups trigger billable external queries and do not expose separate read-only endpoints, write permission is required across the API. Workspace owners and admins have this access by default.
Quelles erreurs une recherche peut-elle renvoyer ?
Lookups return specific error responses when a phone number is missing a valid international country code, when an email address is malformed, when your organization's wallet has insufficient balance to cover the query, or when an upstream lookup service is temporarily unavailable. Failed requests do not charge your wallet.
Une propriété sans réponse fait-elle échouer ma requête ?
No. When an optional enrichment property cannot be resolved, it returns an unavailable or inconclusive status on its own section of the response while the base phone number lookup still succeeds. A request fails outright when the base lookup itself cannot be completed.
Quelles informations une recherche de numéro de téléphone fournit-elle ?
A base phone number lookup returns the number's country, its current serving carrier, the carrier that originally issued the number range, whether the number has been ported between carriers, and its general line type. If the base lookup cannot be resolved, the request returns an error rather than an incomplete response.
Comment dois-je écrire le numéro ?
Format the number in international E.164 order with the country calling code followed by the national number. You can include a leading plus sign, omit it, or use a 00 international prefix, so +31612345678, 31612345678, and 0031612345678 resolve to the same Dutch mobile number.
Pourquoi mon numéro a-t-il été rejeté ?
Numbers written in local national format without a country calling code are rejected instead of guessed. Automatically prepending a country code to a local string like 0612345678 could match an unrelated international number and bill your wallet for the wrong lookup.
Quels types de ligne peuvent être renvoyés ?
The base lookup classifies numbers into mobile, landline, VoIP, toll-free, premium-rate, satellite, pager, payphone, machine-to-machine, service, other, or unknown line types. An unknown result means the carrier registry has no classification for that number range, while other indicates a specialized category outside the standard list. You can request the line classification property when you need finer detail on the allocated service.
Comment savoir si un numéro a été porté ?
The base response includes both the serving carrier that routes the number today and the original carrier that was allocated the number block. When a subscriber moves their number to a new operator, those two carrier blocks differ and the response includes a ported indicator. Add the porting history property when you need the date of the most recent move and the full record of carrier transfers.
Why is the country code missing from my answer?
Some international numbering ranges, such as global satellite or non-geographic services, are not assigned to a single country. When a field has no applicable value, the response omits it rather than returning an empty placeholder, so each field present in the payload reflects a resolved value.
Une recherche appelle-t-elle ou envoie-t-elle un message au numéro ?
No. A lookup does not place a call or send a message to the recipient's device. Base lookups read carrier and numbering registries, and live checks such as network presence and roaming status query operator signaling networks silently without alerting the handset.
Quelles propriétés puis-je ajouter à une recherche de numéro de téléphone ?
You can request up to six optional enrichment properties on a phone number lookup: line classification for the precise service allocated to the number range, number porting history for the dates and carrier records of past network moves, live network presence to check whether the handset is currently reachable, active roaming status and the visited network, SIM swap recency to detect recent SIM card changes, and a credibility score from 0 to 100.
Certaines propriétés sont-elles plus lentes que d'autres ?
Yes. Line classification, number porting history, and the credibility score read indexed registry data and return with minimal latency. Live network presence, active roaming status, and SIM swap recency query the subscriber's mobile operator in real time, so they take longer to resolve and return unavailable or inconclusive statuses more frequently depending on carrier coverage.
Que signifient les statuts des propriétés ?
Each requested property returns its own status. An answered status means the check succeeded, the property data is included in the response, and the property was billed. An unavailable status means the carrier or registry did not return data, at no charge. An inconclusive status means the upstream source responded without enough information to resolve the check definitively, which is also unbilled.
De nouveaux statuts peuvent-ils apparaître ultérieurement ?
Yes. The status field uses an extensible set of values so new diagnostic states can be introduced without breaking existing integrations. Check for an answered status before reading the property data, and treat any other status as an unresolved check.
What do porting history and line classification add over the base answer?
While the base lookup indicates whether a number currently sits on a different carrier than the one that issued its range, the porting history property provides the timestamp of the latest transfer and the historical log of carrier moves. Line classification consults a more granular numbering registry to report the specific service allocated to the range alongside the base line type.
Why did the SIM swap check return a day range instead of an exact date?
Some mobile operators disclose SIM swap recency as a time window rather than an exact timestamp to meet regional privacy rules. When an operator reports a recency band, the response provides the minimum and maximum days since the last SIM change instead of a specific timestamp. Similarly, the porting history property flags when a national registry records the month or period of a carrier transfer rather than the exact calendar day.
Does an unported result mean the porting check failed?
No. When the porting history property reports that a number has not been ported, the national registry confirmed that the number still resides with its original issuing carrier. Check the property status field to see whether the registry query itself succeeded or was unavailable.
Comment dois-je interpréter le score ?
Treat the credibility score as one risk signal alongside line type, porting history, and SIM swap recency. The score ranges from 0 for low credibility to 100 for high credibility based on composite numbering intelligence that goes beyond the other individual properties, so it works best when combined with your own application rules.
Que révèle une recherche d'adresse e-mail ?
An email address lookup tells you whether a mailbox is ready to receive mail before you send to it. One request returns a deliverability verdict, a delivery confidence score from 0 to 100, classification flags for role, disposable, and free consumer inboxes, and a suggested typo correction when the domain looks misspelled.
Quels sont les cinq verdicts ?
A valid verdict means the mailbox exists and accepts mail. A neutral verdict means the receiving server accepts mail for the domain without confirming individual mailboxes, as catch-all domains do. A risky verdict means the address can receive mail but carries higher bounce or complaint risk, such as a disposable or role-based inbox. An undeliverable verdict means the address cannot receive mail, and a typo verdict flags a likely domain misspelling.
Pourquoi une adresse est-elle undeliverable ?
When an address is marked undeliverable, the response specifies whether the failure comes from a syntax error in the address format, a non-existent or unconfigured mail domain, or an invalid mailbox that the receiving domain rejected.
Que faire avec un verdict typo ?
Present the suggested typo correction in your signup or checkout form so the user can confirm it before you send mail. Automatically rewriting an email address without confirmation risks sending sensitive account messages to the wrong person if the original address was intentional.
How does the delivery confidence score differ from the verdict?
The delivery confidence score scales from 0 for an address that will bounce to 100 for a verified, deliverable mailbox. Because different risk factors can produce similar numeric scores under different verdicts, use the verdict to choose the workflow action, such as prompting for a typo fix, and use the confidence score when you want a numeric threshold for list filtering.
How does basic format and domain validity differ from a valid verdict?
The boolean validity indicator checks whether the email address is syntactically well-formed and belongs to a domain configured to accept mail. It does not verify the individual mailbox, so an address at a working domain with a non-existent username passes basic domain validity while still receiving an undeliverable verdict.
Que signifient les flags ?
Role addresses identify shared team inboxes such as support@ or info@, where individual consent is harder to track and complaint rates are higher. Disposable inbox providers issue short-lived throwaway addresses often used to bypass signup gates. Free consumer mail providers such as Gmail or Outlook.com help B2B forms distinguish personal addresses from company domains.
Comment dois-je écrire l'adresse ?
Pass the bare email address without a display name or angle brackets. Addresses wrapped in display-name headers are rejected so the API validates the exact string you store. Preserve the original casing of the local part before the @ symbol, since some mail servers treat local-part casing as significant when scoring deliverability.
Ai-je besoin de Lookup pour arrêter d'envoyer aux adresses qui ont déjà rebondi ?
No. Bird's suppression list automatically blocks repeat sends to addresses that have already bounced or reported spam at no extra charge. Use Lookup to screen new email addresses before your first send, such as during account registration, checkout, or lead import.
Explore the Lookup API
See how phone number verification, email validation, and per-query pricing work across your signup and messaging flows.
- Recherche de numéro de téléphoneIdentify the country, serving and issuing carriers, porting state, line type, and six optional network properties before you send an SMS or place a call.
- Recherche d'adresse e-mailCheck deliverability verdicts, confidence scores, role and disposable inbox flags, and suggested typo corrections before sending email.
- TarifsReview per-query rates for base phone number lookups, email validations, and optional enrichment properties that return an answer.
- L'API LookupValidate phone numbers and email addresses from one API to block fake signups, prevent bounces, and route messages by line type.
Verify recipients before you send a message.
Talk with our team about screening signups, choosing carrier and network checks for your risk model, or sizing throughput for high-volume verification.
Votre prochaine idéeCommencez à développer
Commencez à développerVotre prochaine idée