电话号码智能查询。线路类型、运营商、携号转网来源、欺诈信号。
基于 MNP 感知的运营商查询，运行在承载 Bird SMS 和语音流量的同一网络上。一个端点、相同的认证、相同的错误响应格式——因为它们都出自同一个工程团队。
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 分钟
用您已经在使用的编程语言查询号码。
覆盖所有主流运行时的 SDK。Lookup 中位响应时间低于 300 毫秒——快到足以在发送 SMS 前完成拦截判断。
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
有效性和可达性
返回布尔值 valid 和可达性窗口——有些号码格式正确，但运营商已不再分配。
- 07
批量查询
一次调用中 POST 最多 1,000 个号码。按相同的单号定价计费，节省往返请求开销。
- 08
缓存感知定价
相同输入在 24 小时内的缓存查询免费。只有当结果确实不同时才会计费。
- 09
批量任务 Webhook
对于大批量任务，订阅 lookup.completed 事件并读取结果文件，无需保持 HTTP 长连接。
- 10
相同的认证，相同的错误响应格式
一个 API 密钥通用于 Lookup、SMS、Email、WhatsApp、Voice。统一的错误类型注册表。
我们为什么构建 Lookup
您不应该在 SMS 发送失败后才发现那是个固定电话号码。
我们已经在 Bird SMS 路由内部运行 MNP 查询了——为了实时选择最低成本的运营商路由，这是必须的。Lookup 就是将同一个查询作为一级端点开放出来，让您无需发送任何 SMS 就能拦截注册、评估风险、预测路由成本。与平台其他服务共享相同的认证、错误响应格式和 Webhook。
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查询无法执行；载荷包含错误响应信息。
先查询号码，再发送消息。
相同的认证、相同的幂等性约定、相同的错误响应格式。Lookup 的结构与其他端点一致——区别在于它返回数据，而非发送消息。
Lookup。
await bird.lookup.get({
phone: "+14155550172",
});运营商、线路类型、携号转网来源、欺诈信号——同步返回，耗时低于 300 毫秒。
SMS。
await bird.sms.send({
from: "Bird",
to: "+14155550172",
text: `Your code is ${code}.`,
});相同的认证，相同的错误响应格式。根据查询结果决定是否发送——在产生费用之前过滤掉固定电话号码。