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.
电话号码查询能返回哪些信息？
基础查询会返回号码所属国家、当前服务网络、分配该号段的原始网络、是否曾经携号转网，以及粗略的线路类型。基础查询始终执行，如果无法返回结果，整个请求会失败，而不是返回一个半空的响应。
号码应该怎么写？
先写国家代码，再写国内号码。前导加号可省略，00 也可以替代加号，因此 +31612345678、31612345678 和 0031612345678 都是同一个号码。
为什么我的号码被拒绝了？
如果号码是按国内拨号格式书写、没有国家代码，系统会返回 E22000，而不是猜测号码。因为在 0612345678 前加上一个国家代码可能会指向其他地方的真实号码，并按该号码向您收取查询费用。
可以返回哪些线路类型？
mobile、fixed_line、voip、toll_free、premium_rate、satellite、pager、payphone、m2m、service、other 或 unknown。unknown 表示运营商平台对该号段没有分类记录，other 表示有一个分类但在此处没有对应项。请求 classification 属性可获取更精确的已分配服务信息。
如何判断号码是否已携号转网？
network_info 是当前为该号码提供服务的网络，original_network_info 是最初分配该号段的网络。号码携号转网后两者会不同，此时 flags 中会包含 ported。如果您还需要携号转网日期和完整记录，请请求 porting 属性。
为什么我的结果中没有 country_code？
因为该号码不属于任何单一国家，非地理号段即是如此。没有值的字段会被省略而非返回 null，因此响应中出现的每个字段都已被解析。
查询会拨打或发送消息给该号码吗？
不会。查询绝不会联系号码本身。它读取的是运营商和号码情报数据，presence 和 roaming 属性查询的是号码所注册的网络，因此不会有电话响起，也不会有任何内容到达手机。
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.