基于 Bird 构建客户案例
客户案例基于 Bird 构建
深受工程和产品团队信赖, 助力其在全球范围内交付。
常见问题详解
详解常见问题
Lookup API 常见问题
什么是 Bird Lookup?
Bird Lookup verifies phone numbers and email addresses before you send a message or accept a signup. For a phone number, it returns the country, serving and issuing carriers, porting status, line type, and optional network checks. For an email address, it returns a deliverability verdict, confidence score, inbox type flags, and suggested typo corrections.
我可以查询什么?
You can check phone numbers and email addresses through dedicated endpoints. A phone number lookup returns the country, serving carrier, original issuing carrier, porting status, and line type, along with any optional enrichment properties you request. An email address lookup validates a single address or a synchronous batch and returns a deliverability verdict, confidence score, and address classification flags.
集成的工作量大吗?
A lookup completes in a single synchronous request and response without webhook setup or polling. You can call the REST endpoints directly, use typed methods in the Go, TypeScript, Python, and PHP SDKs, or run phone number and email lookups from the terminal with the Bird CLI.
不写代码可以执行查询吗?
Yes. You can check individual phone numbers and email addresses directly from the Lookup page in the Bird dashboard to inspect carrier details, enrichment properties, and deliverability verdicts before integrating the API.
首次查询前需要准备什么?
You need an API key with lookup write permission and a funded organization wallet. Lookups are billed per query without monthly seat fees or upfront plan commitments.
什么时候应该使用 Lookup 而不是直接发送?
Use Lookup when you want to verify contact details before spending on delivery or admitting an account. Common workflows include blocking disposable emails and virtual numbers at signup, screening lead lists before outreach, and routing OTPs to voice instead of SMS when a number is a landline.
Lookup 如何定价?
Lookups are billed per query from your organization's wallet with no seat fees. A phone number lookup charges a base rate plus an individual fee for each requested enrichment property that returns an answer. An email address lookup charges per validated address.
在哪里查看费率?
The Lookup pricing page lists the per-query rate for a base phone number lookup, each optional enrichment property, and an email address lookup. Property rates vary because each check queries a distinct carrier or intelligence data source.
没有返回结果的属性也需要付费吗?
No. You are charged for an enrichment property when it returns a resolved answer. If a property is unavailable or inconclusive, its status explains why at no charge for that property, and you still receive the base phone number lookup.
查询失败会产生费用吗?
失败的请求不计费。如果电话号码或单个电子邮件地址格式错误,或者无法连接上游数据源,您的钱包不会被扣费。电子邮件批量请求会为每个地址返回一条评估结果并逐一计费,格式错误的地址也包括在内。
查询结果为不可送达的地址也会计费吗?
Yes. Validated email addresses are billed regardless of the deliverability verdict, including undeliverable addresses. Identifying an invalid mailbox upfront prevents a hard bounce and protects your sender reputation.
重试会被重复收费吗?
在 POST 查询请求中发送 Idempotency-Key。在同一工作区内,三小时内使用相同密钥发起完全相同的请求进行重试,会返回已存储的响应,不会再次执行查询或扣费。超过三小时后,或者响应未被保存时(例如大于 256 KiB 的电子邮件批次响应),重试可能会再次执行查询或批次并再次扣费。GET 形式会将号码或地址放在 URL 中,不接受幂等键,因此自动化工作流请使用 POST 端点。
每分钟可以执行多少次查询?
这取决于您组织的 Lookup 请求速率限制。您的组织在其所有 API 密钥和工作区之间共享该限制,因此新建密钥不会增加容量;一个最多包含 1,000 个地址的电子邮件批次计为一次请求。Lookup 响应中的速率限制响应头会显示适用于您请求的限制。由于每次查询都会访问外部运营商或域名数据源,并从您的钱包扣费,新组织的初始限制较为保守。随着用量增长,请联系我们提高限制;如需了解如何解读这些响应头,请参阅文档中的 Rate limits 指南。
是否支持批量查询?
Email address lookup supports synchronous batches of up to 1,000 addresses in a single request, with a maximum request body of 128 KiB. Phone number lookup checks one number per request, and you can contact us to raise your rate limit for higher-throughput phone verification.
查询需要什么权限范围?
Lookup endpoints require the lookup permission scope with write access. Because lookups trigger billable external queries and do not expose separate read-only endpoints, write permission is required across the API. Workspace owners and admins have this access by default.
查询可能返回哪些错误?
Lookups return specific error responses when a phone number is missing a valid international country code, when an email address is malformed, when your organization's wallet has insufficient balance to cover the query, or when an upstream lookup service is temporarily unavailable. Failed requests do not charge your wallet.
无法返回结果的属性会导致请求失败吗?
No. When an optional enrichment property cannot be resolved, it returns an unavailable or inconclusive status on its own section of the response while the base phone number lookup still succeeds. A request fails outright when the base lookup itself cannot be completed.
电话号码查询能返回哪些信息?
A base phone number lookup returns the number's country, its current serving carrier, the carrier that originally issued the number range, whether the number has been ported between carriers, and its general line type. If the base lookup cannot be resolved, the request returns an error rather than an incomplete response.
号码应该怎么写?
Format the number in international E.164 order with the country calling code followed by the national number. You can include a leading plus sign, omit it, or use a 00 international prefix, so +31612345678, 31612345678, and 0031612345678 resolve to the same Dutch mobile number.
为什么我的号码被拒绝了?
Numbers written in local national format without a country calling code are rejected instead of guessed. Automatically prepending a country code to a local string like 0612345678 could match an unrelated international number and bill your wallet for the wrong lookup.
可以返回哪些线路类型?
The base lookup classifies numbers into mobile, landline, VoIP, toll-free, premium-rate, satellite, pager, payphone, machine-to-machine, service, other, or unknown line types. An unknown result means the carrier registry has no classification for that number range, while other indicates a specialized category outside the standard list. You can request the line classification property when you need finer detail on the allocated service.
如何判断号码是否已携号转网?
The base response includes both the serving carrier that routes the number today and the original carrier that was allocated the number block. When a subscriber moves their number to a new operator, those two carrier blocks differ and the response includes a ported indicator. Add the porting history property when you need the date of the most recent move and the full record of carrier transfers.
Why is the country code missing from my answer?
Some international numbering ranges, such as global satellite or non-geographic services, are not assigned to a single country. When a field has no applicable value, the response omits it rather than returning an empty placeholder, so each field present in the payload reflects a resolved value.
查询会拨打或发送消息给该号码吗?
No. A lookup does not place a call or send a message to the recipient's device. Base lookups read carrier and numbering registries, and live checks such as network presence and roaming status query operator signaling networks silently without alerting the handset.
电话号码查询可以添加哪些属性?
You can request up to six optional enrichment properties on a phone number lookup: line classification for the precise service allocated to the number range, number porting history for the dates and carrier records of past network moves, live network presence to check whether the handset is currently reachable, active roaming status and the visited network, SIM swap recency to detect recent SIM card changes, and a credibility score from 0 to 100.
某些属性的查询速度会更慢吗?
Yes. Line classification, number porting history, and the credibility score read indexed registry data and return with minimal latency. Live network presence, active roaming status, and SIM swap recency query the subscriber's mobile operator in real time, so they take longer to resolve and return unavailable or inconclusive statuses more frequently depending on carrier coverage.
属性状态分别代表什么含义?
Each requested property returns its own status. An answered status means the check succeeded, the property data is included in the response, and the property was billed. An unavailable status means the carrier or registry did not return data, at no charge. An inconclusive status means the upstream source responded without enough information to resolve the check definitively, which is also unbilled.
以后会出现新的状态值吗?
Yes. The status field uses an extensible set of values so new diagnostic states can be introduced without breaking existing integrations. Check for an answered status before reading the property data, and treat any other status as an unresolved check.
What do porting history and line classification add over the base answer?
While the base lookup indicates whether a number currently sits on a different carrier than the one that issued its range, the porting history property provides the timestamp of the latest transfer and the historical log of carrier moves. Line classification consults a more granular numbering registry to report the specific service allocated to the range alongside the base line type.
Why did the SIM swap check return a day range instead of an exact date?
Some mobile operators disclose SIM swap recency as a time window rather than an exact timestamp to meet regional privacy rules. When an operator reports a recency band, the response provides the minimum and maximum days since the last SIM change instead of a specific timestamp. Similarly, the porting history property flags when a national registry records the month or period of a carrier transfer rather than the exact calendar day.
Does an unported result mean the porting check failed?
No. When the porting history property reports that a number has not been ported, the national registry confirmed that the number still resides with its original issuing carrier. Check the property status field to see whether the registry query itself succeeded or was unavailable.
如何解读评分?
Treat the credibility score as one risk signal alongside line type, porting history, and SIM swap recency. The score ranges from 0 for low credibility to 100 for high credibility based on composite numbering intelligence that goes beyond the other individual properties, so it works best when combined with your own application rules.
邮箱地址查询能返回什么信息?
An email address lookup tells you whether a mailbox is ready to receive mail before you send to it. One request returns a deliverability verdict, a delivery confidence score from 0 to 100, classification flags for role, disposable, and free consumer inboxes, and a suggested typo correction when the domain looks misspelled.
五种判定结果分别是什么?
A valid verdict means the mailbox exists and accepts mail. A neutral verdict means the receiving server accepts mail for the domain without confirming individual mailboxes, as catch-all domains do. A risky verdict means the address can receive mail but carries higher bounce or complaint risk, such as a disposable or role-based inbox. An undeliverable verdict means the address cannot receive mail, and a typo verdict flags a likely domain misspelling.
为什么地址会被判定为不可投递?
When an address is marked undeliverable, the response specifies whether the failure comes from a syntax error in the address format, a non-existent or unconfigured mail domain, or an invalid mailbox that the receiving domain rejected.
收到 typo 判定结果后应该怎么做?
Present the suggested typo correction in your signup or checkout form so the user can confirm it before you send mail. Automatically rewriting an email address without confirmation risks sending sensitive account messages to the wrong person if the original address was intentional.
How does the delivery confidence score differ from the verdict?
The delivery confidence score scales from 0 for an address that will bounce to 100 for a verified, deliverable mailbox. Because different risk factors can produce similar numeric scores under different verdicts, use the verdict to choose the workflow action, such as prompting for a typo fix, and use the confidence score when you want a numeric threshold for list filtering.
How does basic format and domain validity differ from a valid verdict?
The boolean validity indicator checks whether the email address is syntactically well-formed and belongs to a domain configured to accept mail. It does not verify the individual mailbox, so an address at a working domain with a non-existent username passes basic domain validity while still receiving an undeliverable verdict.
各标志位是什么意思?
Role addresses identify shared team inboxes such as support@ or info@, where individual consent is harder to track and complaint rates are higher. Disposable inbox providers issue short-lived throwaway addresses often used to bypass signup gates. Free consumer mail providers such as Gmail or Outlook.com help B2B forms distinguish personal addresses from company domains.
地址应该怎么写?
Pass the bare email address without a display name or angle brackets. Addresses wrapped in display-name headers are rejected so the API validates the exact string you store. Preserve the original casing of the local part before the @ symbol, since some mail servers treat local-part casing as significant when scoring deliverability.
我需要用 Lookup 来停止向已退信的地址发送邮件吗?
No. Bird's suppression list automatically blocks repeat sends to addresses that have already bounced or reported spam at no extra charge. Use Lookup to screen new email addresses before your first send, such as during account registration, checkout, or lead import.
Explore the Lookup API
See how phone number verification, email validation, and per-query pricing work across your signup and messaging flows.
- 电话号码查询Identify the country, serving and issuing carriers, porting state, line type, and six optional network properties before you send an SMS or place a call.
- 电子邮件地址查询Check deliverability verdicts, confidence scores, role and disposable inbox flags, and suggested typo corrections before sending email.
- 定价Review per-query rates for base phone number lookups, email validations, and optional enrichment properties that return an answer.
- Lookup APIValidate phone numbers and email addresses from one API to block fake signups, prevent bounces, and route messages by line type.
Verify recipients before you send a message.
Talk with our team about screening signups, choosing carrier and network checks for your risk model, or sizing throughput for high-volume verification.