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.
A cosa risponde una ricerca di numero di telefono?
La ricerca base restituisce il paese del numero, la rete che lo serve attualmente, la rete che ha assegnato il suo range, se è mai stato trasferito su un'altra rete e un tipo di linea generico. Viene sempre eseguita e, se non è possibile ottenere una risposta, l'intera richiesta fallisce anziché restituire una risposta incompleta.
Come devo scrivere il numero?
Prima il prefisso internazionale, poi il numero nazionale. Il segno più iniziale è opzionale e 00 funziona al suo posto, quindi +31612345678, 31612345678 e 0031612345678 sono tutti lo stesso numero.
Perché il mio numero è stato rifiutato?
Un numero scritto per la composizione interna a un paese, senza prefisso internazionale, restituisce E22000 anziché essere interpretato a indovinare. Anteporre un prefisso internazionale a 0612345678 indicherebbe un numero reale altrove e vi addebiterebbe la ricerca di quel numero.
Quali tipi di linea può restituire?
mobile, fixed_line, voip, toll_free, premium_rate, satellite, pager, payphone, m2m, service, other o unknown. unknown significa che la piattaforma dell'operatore non ha una classificazione per il range, e other significa che ne ha una senza equivalente qui. Richiedete la proprietà classification per il servizio assegnato con maggiore precisione.
Come faccio a sapere se un numero è stato portato?
network_info è la rete che serve il numero oggi e original_network_info è la rete che ha assegnato il suo range. Le due differiscono quando un numero è stato portato e, in tal caso, flags contiene ported. Richiedete la proprietà porting quando avete bisogno anche della data e del record completo.
Perché country_code manca dalla mia risposta?
Perché il numero non appartiene a un singolo paese, come nel caso di un range non geografico. I campi senza valore vengono omessi anziché restituiti come null, quindi ogni campo presente nella risposta è stato risolto.
Una ricerca chiama o invia messaggi al numero?
No. Una ricerca non contatta mai il numero stesso. Legge i dati dell'operatore e di number intelligence, e le proprietà presence e roaming interrogano la rete su cui il numero è registrato, quindi nulla squilla e nulla arriva sul dispositivo.
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.