Start with the right destination.
Help your application understand the number or address the customer has provided.
Phone Number Lookup API
Phone lookup API.
Know before you connect.
Check a phone number’s country, carrier and line type before sending a message. Use the returned signals to choose a contact channel or ask the customer to correct their number.
Lookup / InputPHONE NUMBER
+1 555 000 0142
⌕+1 555 000 0142↗
Continue the appropriate destination checks.
Destination evidence- Country
- United States
- Line type
- Mobile
- Carrier
- Example Wireless
- Ownership
- Not established
Lookup / InputEMAIL ADDRESS
alex@example.com
⌕alex@example.com↗
Use address evidence, then apply your own policy.
Destination evidence- Result
- valid · example
- Confidence
- 94 / 100 · example
- Ownership
- Not established
- Permission
- Not established
Lookup / InputUNAVAILABLE EVIDENCE
+1 555 000 0199
⌕+1 555 000 0199↗
Do not turn a missing signal into a rejection.
Destination evidence- Line type
- Unknown
- Carrier
- Unavailable
- Optional score
- Unavailable
- Meaning
- Evidence is missing
Example content and data. Explore the workflow below; nothing is sent or changed in a live account.
Companies that trust Bird across their communications.
Read Bird customer storiesBIRD LOOKUPEvidence with its limits.
DOCUMENTED OPERATING BEHAVIORAn answer.
An answer.
A deliberate next step.
The maintained Lookup guides distinguish the baseline, independently answered properties and one email verdict. An unavailable property can leave the baseline useful; a negative answered verdict can still be billed.
Read the maintained Lookup guide ↗Sources checked 18 September 2026. Synthetic examples demonstrate interpretation, not measured accuracy, supplier coverage or a live customer result. Confirm current account access before launch.Lookup / phone evidence
Read the answer before the action.
Inspect a controlled number and its independent network signals. Change an observation to see how the next messaging decision changes.
ILLUSTRATIVE LOOKUP / L-316Phone number
+31 6 1234 5678
Input: +31612345678
Original networkVodafone
→Serving networkKPN
- country_code
- NL
- line_type
- mobile
- flags
- ported
Carrier examples come from the maintained code sample. Country and network fields can be absent when unresolved; do not fill them from a display label.
National-only input is rejected rather than assigned a guessed country. Prepare the international form before requesting a result.
Independent property observations
presenceok
reachable: true
roamingok
is_roaming: false
Continue to your messaging policy
Reachable false is a known negative answer. An unavailable property has no usable value. It remains an answered unit. Review timing or another appropriate route before sending.
No presence block was returned. Absence is not a false value or an answered presence unit.
A fixed-line or unknown line type requires its own channel policy. Do not infer SMS support from a formatted number.
The source reports a reachable mobile line. Confirm the recipient’s consent and your sending policy before a separate message request.
No baseline or property result is established for this input. Select an international example to continue.
A lookup does not establish identity, ownership, permission to contact or future delivery. Roaming is independent of reachability and cannot replace those checks.
Read the response contract ↗Illustrative observations only. No number is queried and no message is sent.
WHAT IT MEANS FOR YOUR CUSTOMERBetter information.
Better information.
A better next decision.
Catch a detail while it is still easy to correct. Use phone and email evidence to make the next customer step more informed, without treating an unknown answer as a failed person.
Read the useful signals.
Use the returned classification and supported properties, including their status and confidence.
Make the next step clear.
Ask for a correction, continue, or verify control according to the decision your product needs to make.
FIND YOUR WAY IN
Evidence has a scope.
Understand the number.
Read serving/original network, country when resolved, coarse line type and six optional properties. Treat unknown signals separately from answered negatives.
Explore phone lookup ↗Catch the small mistake.
Use validation evidence and typo suggestions in your email collection flow. Ownership and permission remain separate questions.
Explore Email validation ↗READY WHEN YOU ARE
Start with the detail you have.
BUILD WITH LOOKUPPut the evidence
Put the evidence
to useful work.
Run a phone lookup on your server and check each property’s status before using its value. The guide covers credentials, region, paid queries and unavailable signals.
Run the same phone lookup with the CLI or MCP and inspect each returned signal. Carrier and number information does not establish identity or possession.
Open the implementation guide →npm install @messagebird/sdkconst 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);THE COMPLETE BIRD PLATFORM
Better inputs. Better next steps.
Connect Lookup to signup, verification, and messaging. Each product handles a distinct job while your application keeps the customer journey together.
LOOKUPThe number,
in context.
in context.
- Line type
- Mobile
- Ownership
- Not established
01
Lookup This step
Inspect Alex’s submitted destination.
VERIFYA verified
beginning.
beginning.
- Request
- vrf_example
- Code check
- Verified
02
Verify ↗
Verify control when your account flow requires it.
12
f.Fieldnotes
Today · 9:41
Your account update is ready, Alex.
View the details in your account.
03
SMS ↗
Send an application update after the customer chooses the channel.
LEARN / BUILD / OPERATEGo further with
FIELD GUIDE
Go further with
Lookup.
FIELD GUIDEEvidence has a scope.
A practical path through setup, implementation, and the choices that matter.
Read the field guide →Explore all resources
Quickstarts, implementation guides, comparisons and migration.
Look up a phone number
Request the properties your decision needs.
Look up an email address
Read result and confidence together.
Choose phone or email
Match the operation to your next decision.
Prepare your first lookup
Check credentials, wallet and recovery.
Lookup questions
41 direct answers about signals, limits and billing.
Estimate Lookup costs
Count baseline and answered-property units.
Follow concrete recipient decisions, handle unavailable evidence and keep possession and permission separate.
LOOKUP / PRICINGChoose the evidence.
Choose the evidence.
Know the scope.
Every answered phone lookup has a baseline charge. Each requested optional property adds a charge only with status ok. Budget email verdicts and downstream verification separately.
See Lookup pricing ↗YOUR LOOKUP SETUPBase + properties
Request the evidence your application needs.
- Your request
- Phone and email checks serve different decisions.
- Optional evidence
- Review property availability and successful-result charges.
- The next step
- Budget verification and downstream messaging separately.
A FEW USEFUL ANSWERS
Lookup, answered.
Quelles informations une recherche de numéro de téléphone fournit-elle ?
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.
Comment dois-je écrire le numéro ?
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.
Pourquoi mon numéro a-t-il été rejeté ?
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.
Quels types de ligne peuvent être renvoyés ?
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.
Comment savoir si un numéro a été porté ?
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.
Pourquoi country_code est-il absent de ma réponse ?
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.
Une recherche appelle-t-elle ou envoie-t-elle un message au numéro ?
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.
Does Lookup prove who owns a number?
No. Lookup provides information about a destination. Verification is a separate step for confirming that someone can receive and return a code.
Should I reject an unknown result?
Unknown is different from invalid. Some result blocks may be unavailable. Your application should make a deliberate decision using the evidence it has.
Can I treat an unavailable property as false?
No. Read its status and preserve uncertainty. A missing result can reflect unavailable evidence rather than a negative answer.
Is Lookup the same as Verify?
Lookup provides information about a destination. Verify checks control by delivering and checking a code. Use the capability that matches the decision.
How do I get started or speak to sales?
Start with a Bird account and follow the setup path on this page. Our sales team can help with migration, volume, or a wider product mix. Start now or talk to sales.