Lookup API 常见问题

Lookup 在您发送消息之前回答关于收件人的问题。输入一个电话号码，它会告诉您该号码的详情：服务网络、所属国家、是否携号转网，以及线路类型。输入一个邮箱地址，它会告诉您该地址是否值得发送。

两类查询，各一个操作。电话号码查询返回所属国家、当前服务网络、发号网络、是否在两者之间发生过携号转网，以及线路类型，还有您请求的任何附加属性。邮箱地址查询返回一个判定结果、一个置信度评分以及相关标志位。

每次查询只需一个请求和一个响应。无需创建资源、无需轮询、无需事后清理。Go、TypeScript、Python 和 PHP SDK 提供了类型化方法，CLI 中的 bird lookup phone-number 和 bird lookup email 命令可实现相同功能。

可以。控制台中的 Lookup 页面支持逐条执行同样的两种查询操作，这是在正式集成之前了解返回结果的最快方式。

一个具有 lookup 权限范围的 API 密钥，以及一个余额足以支付费用的组织钱包。按查询计费，无席位费，因此无需事先选择套餐。

当您希望在执行之前做出判断时使用：在注册环节进行验证、在处理潜在客户之前进行筛查，或根据线路类型以不同方式路由消息。您无需先发送任何内容即可获得可操作的结果。

按查询次数计费。每次查询从您组织的钱包余额中扣费。电话号码查询收取一次基础查询费，加上每个返回结果的属性各一次费用。电子邮件地址查询按每个有结果的地址收取一次费用。无席位费。

Lookup 定价页面列出了基础查询、每个属性以及电子邮件地址查询的费率。费率因属性而异，因为每个属性来自不同的数据源。

不需要。属性仅在返回结果时才计费。无法解答的属性会返回一个说明状态，不产生任何费用，基础查询仍然会正常返回。

不会产生任何费用。格式错误的号码、被拒绝的地址以及无法访问的数据源都不收费。

是的。每个有结果的地址都会计费，包括不可送达的地址。这正是您请求的答案，也正是帮您避免退信的答案。

如果您发送了 Idempotency-Key，就不会。相同请求的重复提交会返回已存储的结果，而不会执行新的查询。GET 方式将号码或地址放在 URL 中，无法携带幂等键，因此自动化场景请使用 POST。

查询速率限制起始为每分钟 10 次请求，按操作凭证计数，因此一个繁忙的密钥不会影响其他密钥。每次查询都会访问外部数据源并从您的钱包扣费，这就是为什么它的初始限额与发送限额相同。

目前不支持。两种操作都没有批量形式，因此不适合用来检查整个列表。如果您有批量需求，请联系我们提高限额，而不是自行绕过限制。

lookup 权限范围的写入级别。它没有读取级别：所有查询端点都需要写入权限，包括获取您已付费的结果。Owner 和 Admin 默认拥有该权限，Member 则没有。

四个重要的错误。E22000 表示号码不是有效的国际格式，E22003 表示地址不是有效的邮箱地址，E22001 表示组织钱包余额不足以支付查询费用，E22002 表示 Lookup 暂时不可用。以上错误均不会产生费用。

不会。失败的属性会在其自身的区块中以状态形式返回，基础查询结果会一同返回。只有基础查询本身失败才会导致请求失败，且会直接报错，而不是返回一个需要您逐一检查才能发现缺失的半空响应。

基础查询会返回号码所属国家、当前服务网络、分配该号段的原始网络、是否曾经携号转网，以及粗略的线路类型。基础查询始终执行，如果无法返回结果，整个请求会失败，而不是返回一个半空的响应。

先写国家代码，再写国内号码。前导加号可省略，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 属性。

因为该号码不属于任何单一国家，非地理号段即是如此。没有值的字段会被省略而非返回 null，因此响应中出现的每个字段都已被解析。

不会。查询绝不会联系号码本身。它读取的是运营商和号码情报数据，presence 和 roaming 属性查询的是号码所注册的网络，因此不会有电话响起，也不会有任何内容到达手机。

六个，在 type 中指定。classification 用于获取该号段精确的已分配服务；porting 用于查询号码上次携号转网的时间及所有转网记录；presence 用于查询号码当前是否在网；roaming 用于查询号码是否正在漫游及所在网络；sim_swap 用于查询 SIM 卡上次更换的时间；score 用于获取 0 到 100 的可信度评分。

是的。classification、porting 和 score 读取存储数据，返回较快。presence、roaming 和 sim_swap 需要访问实时网络，因此较慢，且覆盖范围因运营商而异。这三个属性返回 unavailable 或 inconclusive 的频率会高于存储类属性。

ok 表示属性已返回结果，值在响应中，已计费。unavailable 表示未获取到结果，不计费。inconclusive 表示收到了响应但无法确定属性值，这本身也是一个有效发现，同样不计费。

会。status 是一个开放词汇表。只需判断 ok，其余一律视为未返回结果，这样无论词汇表如何扩展，您的代码都能正确运行。

porting 提供转网日期和完整历史记录，而基础查询的 ported 标志只能表明是否曾发生过转网。classification 将 line_type 解析为精确的已分配服务，使用不同的数据源和更丰富的词汇表，并且单独报告，因此您始终能区分两者。

因为网络不提供精确数值。当只能获取到大致时间段时，sim_swap 会返回 min_days 和 max_days 而非 last_swapped_at。porting 也有类似情况：当注册表只记录了转网的时间段而非具体日期时，会设置 last_ported_at_is_approximate。

不是。这表示已查询注册表且未记录该号码的转网信息，这是关于号码的一个确切结论，而非查询结果的缺失。该数据块上的 status 才能告诉您检查是否成功执行。

将其作为多个信号之一来参考。评分范围从 0（低可信度）到 100（高可信度），它是一个综合评分，无法从其他属性推导得出。请结合其余返回结果综合判断，而非仅凭该评分做出决策。

该地址是否接收邮件。一次调用即可返回 result 中的判定结果、delivery_confidence 评分、描述地址类型的标志位，以及当地址疑似拼写错误时的修正建议。

valid 表示地址存在且接收邮件，可以发送。neutral 表示无法确认，通常是因为接收域对所有收件人返回相同响应。risky 表示可能接收邮件，但比一般地址更容易退信或投诉。undeliverable 表示不接收邮件。typo 表示地址看起来拼写有误。

reason 会说明三种问题中的哪一种：invalid_syntax 表示地址格式错误，invalid_domain 表示该域名完全不接收邮件，invalid_recipient 表示域名接收邮件但该邮箱不存在。

将 did_you_mean 的建议展示给输入原始地址的用户，而不是直接向该地址发送邮件。修正建议只是猜测，用户实际想输入的地址可能两者都不是。

它的范围从 0（确定无法投递）到 100（确定可以投递）。相同的分数可能因为不同原因出现在不同的判定结果下，因此应将其与 result 结合阅读，而非替代 result。当您需要对所有判定结果（包括未来新增的判定）设定统一阈值时，这是应该依赖的字段。

不是，两者的区别很重要。valid 字段的范围更窄：它只判断地址格式是否正确以及其域名是否配置为接收邮件。它不涉及邮箱本身，因此一个域名正常但邮箱不存在的地址，valid 字段为 true，但 result 中为 undeliverable。

role 表示该地址对应的是一个职能而非个人，例如 support@ 或 info@，因此回复和授权同意具有歧义，投诉的可能性也更高。disposable 表示一次性邮箱提供商，该地址通常会很快失效。free_provider 表示消费级邮箱提供商，如 Gmail 或 Outlook.com，仅在您期望收到企业邮箱地址时才有参考意义。

发送裸地址，与您存储的格式完全一致。带显示名称的格式（名称在前，地址用尖括号包裹）会被直接拒绝而不会被解析，因为解析后查询的地址并非您提交的地址。@ 符号前面的部分按原样传递，大小写的改变可能会影响返回的 delivery_confidence。

不需要。抑制列表会自动且免费地处理已退信或已投诉的地址。Lookup 用于您尚未发送过邮件的地址，例如在注册时或处理潜在客户之前。