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.
Was beantwortet eine Telefonnummern-Abfrage?
Die Basisabfrage liefert das Land der Nummer, das aktuell zuständige Netz, das Netz, das den Nummernbereich vergeben hat, ob die Nummer jemals das Netz gewechselt hat, und einen groben Leitungstyp. Sie wird immer ausgeführt, und wenn sie nicht beantwortet werden kann, schlägt die gesamte Anfrage fehl, anstatt eine halb leere Antwort zurückzugeben.
Wie sollte ich die Nummer schreiben?
Zuerst die Landesvorwahl, dann die nationale Nummer. Das führende Plus ist optional, und 00 funktioniert als Ersatz – +31612345678, 31612345678 und 0031612345678 bezeichnen also dieselbe Nummer.
Warum wurde meine Nummer abgelehnt?
Eine Nummer, die für die Inlandswahl ohne Landesvorwahl geschrieben ist, gibt E22000 zurück, statt geraten zu werden. Würde man eine Landesvorwahl vor 0612345678 setzen, würde das eine reale Nummer anderswo bezeichnen – und Ihnen diese Abfrage in Rechnung stellen.
Welche Leitungstypen kann die Abfrage zurückgeben?
mobile, fixed_line, voip, toll_free, premium_rate, satellite, pager, payphone, m2m, service, other oder unknown. unknown bedeutet, dass die Carrier-Plattform keine Klassifizierung für den Bereich führt, und other bedeutet, dass sie eine führt, die hier keine Entsprechung hat. Fragen Sie die Eigenschaft classification ab, um den zugewiesenen Dienst mit feinerer Auflösung zu erhalten.
Wie erkenne ich, ob eine Nummer portiert wurde?
network_info ist das Netz, das die Nummer aktuell bedient, und original_network_info ist das Netz, das den Bereich vergeben hat. Die beiden unterscheiden sich, sobald eine Nummer portiert wurde, und flags enthält in diesem Fall ported. Fragen Sie die Eigenschaft porting ab, wenn Sie auch das Datum und den vollständigen Datensatz benötigen.
Warum fehlt country_code in meiner Antwort?
Weil die Nummer keinem einzelnen Land zugehört, wie es bei einem nicht-geografischen Nummernbereich der Fall ist. Felder ohne Wert werden weggelassen statt als null zurückgegeben, sodass jedes in der Antwort vorhandene Feld tatsächlich aufgelöst wurde.
Ruft eine Abfrage die Nummer an oder sendet ihr eine Nachricht?
Nein. Eine Abfrage kontaktiert die Nummer selbst niemals. Sie liest Carrier- und Nummern-Informationsdaten, und die Eigenschaften presence und roaming befragen das Netz, in dem die Nummer registriert ist – es klingelt also nichts, und auf dem Gerät kommt nichts an.
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.