电话号码智能查询。线路类型、运营商、携号转网来源、欺诈信号。
MNP-aware carrier lookup over the same wires that carry Bird's SMS and Voice traffic. One endpoint, same auth, same error envelope as every other Bird channel, because the same engineering team built them all.
import { BirdClient } from "@messagebird/sdk";
const bird = new BirdClient({ apiKey: process.env.BIRD_API_KEY! });
const { data, error } = await bird.lookup.get({
phone: "+14155550172",
}).safe();
if (error) throw error;
console.log(data);
// → {
// phone: "+14155550172",
// line_type: "mobile",
// carrier: "T-Mobile USA",
// country: "US",
// ported_from: "AT&T Mobility",
// fraud_score: 0.07,
// valid: true,
// }
从 npm install 到首次查询仅需 5 分钟
用您已经在使用的编程语言查询号码。
SDKs in every major runtime. Lookup answers in under 300ms at the median, fast enough to gate an SMS send on it.
import { BirdClient } from "@messagebird/sdk";
const bird = new BirdClient({ apiKey: process.env.BIRD_API_KEY! });
const { data, error } = await bird.lookup.get({
phone: "+14155550172",
}).safe();十个数据字段，否则您需要从三家供应商分别拼凑。
具体的数据点，命名明确、可审计。每一条都来自真实数据源，而非模型猜测。
- 01
线路类型检测
移动电话、固定电话、VoIP、免费电话、增值电话、寻呼机。在发送前判断该号码是否支持 SMS。
- 02
运营商识别
根据 E.164 格式输入返回当前运营商名称和国家代码。持续对照 MNP 注册数据库更新。
- 03
携号转网历史
该号码此前从哪家运营商转出。可用于路由成本预测和欺诈启发式分析。
- 04
国家和地区格式
返回 E.164、国内和国际格式；路由器所需的国家和地区代码。
- 05
欺诈信号
每个号码返回 0-1 的 fraud_score，综合速率、线路类型启发式、近期携号转网标记和已知恶意名单。
- 06
有效性和可达性
A boolean valid and a reachable window: some numbers parse fine but the carrier no longer assigns them.
- 07
批量查询
一次调用中 POST 最多 1,000 个号码。按相同的单号定价计费，节省往返请求开销。
- 08
缓存感知定价
相同输入在 24 小时内的缓存查询免费。只有当结果确实不同时才会计费。
- 09
批量任务 Webhook
对于大批量任务，订阅 lookup.completed 事件并读取结果文件，无需保持 HTTP 长连接。
- 10
相同的认证，相同的错误响应格式
一个 API 密钥通用于 Lookup、SMS、Email、WhatsApp、Voice。统一的错误类型注册表。
我们为什么构建 Lookup
您不应该在 SMS 发送失败后才发现那是个固定电话号码。
We were already running MNP lookups inside Bird SMS routing: we had to, to pick the cheapest carrier route in real time. Lookup is that same query, surfaced as a first-class endpoint, so you can gate signups, score risk, and forecast routing cost without sending a single SMS. Same auth, same error envelope, same webhooks as the rest of the platform.
import { BirdClient } from "@messagebird/sdk";
const bird = new BirdClient({ apiKey: process.env.BIRD_API_KEY! });
const { data, error } = await bird.lookup.get({
phone: "+14155550172",
}).safe();
if (error) throw error;
console.log(data);
// → {
// phone: "+14155550172",
// line_type: "mobile",
// carrier: "T-Mobile USA",
// country: "US",
// ported_from: "AT&T Mobility",
// fraud_score: 0.07,
// valid: true,
// }
每次状态变更都是一个 Webhook。
HMAC 签名的载荷，防重放，幂等。单号查询为同步返回；批量查询以 Webhook 方式分发。
{
"type": "lookup.completed",
"id": "evt_2qB72y...",
"created_at": "2026-05-19T15:42:01.221Z",
"data": {
"lookup_id": "lkp_4hQ8m2nT",
"phone": "+14155550172",
"line_type": "mobile",
"carrier": "T-Mobile USA",
"country": "US",
"ported_from": "AT&T Mobility",
"fraud_score": 0.07,
"valid": true
}
}
重试计划：5 秒、30 秒、5 分钟、30 分钟、2 小时、6 小时、12 小时。最终尝试后进入死信队列；每个死信事件均可从控制台或 API 重放。
lookup.completed查询（单个或批量）已完成。载荷包含完整响应。lookup.failed查询无法执行；载荷包含错误响应信息。
先查询号码，再发送消息。
Same auth, same idempotency contract, same error envelope. Lookup is shaped like every other endpoint. The difference is that it returns data instead of dispatching a message.
Lookup。
await bird.lookup.get({
phone: "+14155550172",
});
Carrier, line type, ported-from, fraud signals: returned synchronously in under 300ms.
SMS。
await bird.sms.send({
from: "Bird",
to: "+14155550172",
text: `Your code is ${code}.`,
category: "authentication",
});
Same auth, same error envelope. Gate the send on the lookup result: drop the landlines before they cost you.