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.
Wat geeft een telefoonnummer-lookup als antwoord?
De basislookup geeft het land van het nummer, het netwerk dat het momenteel bedient, het netwerk dat het nummerbereik heeft uitgegeven, of het ooit van netwerk is gewisseld, en een globaal lijntype. De basislookup wordt altijd uitgevoerd, en als er geen antwoord kan worden gegeven, mislukt het hele verzoek in plaats van een half leeg antwoord te retourneren.
Hoe moet ik het nummer schrijven?
Eerst het landnummer, dan het nationale nummer. De plus aan het begin is optioneel en 00 werkt als vervanging, dus +31612345678, 31612345678 en 0031612345678 zijn allemaal hetzelfde nummer.
Waarom is mijn nummer afgewezen?
Een nummer dat is geschreven voor binnenlands bellen, zonder landcode, retourneert E22000 in plaats van te worden geraden. Een landcode vóór 0612345678 plakken zou een bestaand nummer ergens anders aanduiden en u kosten in rekening brengen voor het opzoeken van dát nummer.
Welke lijntypen kan het retourneren?
mobile, fixed_line, voip, toll_free, premium_rate, satellite, pager, payphone, m2m, service, other of unknown. unknown betekent dat het carrierplatform geen classificatie heeft voor het bereik, en other betekent dat het er wel een heeft zonder equivalent hier. Vraag de classification-eigenschap op voor de toegewezen dienst met hogere precisie.
Hoe kan ik zien of een nummer is geporteerd?
network_info is het netwerk dat het nummer momenteel bedient en original_network_info is het netwerk dat het bereik heeft uitgegeven. Die twee verschillen zodra een nummer is geporteerd, en flags bevat dan ported. Vraag de porting-eigenschap op als u ook de datum en het volledige record nodig hebt.
Waarom ontbreekt country_code in mijn antwoord?
Omdat het nummer niet tot één enkel land behoort, zoals bij een niet-geografisch bereik. Velden zonder waarde worden weggelaten in plaats van als null geretourneerd, dus elk veld dat in het antwoord aanwezig is, is daadwerkelijk opgelost.
Belt of berichtt een lookup het nummer?
Nee. Een lookup neemt nooit contact op met het nummer zelf. Het leest carrier- en nummerintelligentiegegevens, en de presence- en roaming-eigenschappen bevragen het netwerk waarop het nummer is geregistreerd, dus er gaat niets over en er komt niets aan op het toestel.
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.