sinch-number-lookup-api

Sinch Number Lookup API

概览

查询电话号码的运营商、线路类型、携号转网、SIM 卡更换、VoIP 检测和号码重新分配检测信息。用于防范欺诈、路由和数据丰富。每个请求只能查询一个号码，不提供批量查询接口。

Agent 指南

策略门控 sinch-shared-policy@5（sha256:4864cf0fa8d6）： 以下策略摘要具有约束力，须按原文执行。在实施或进行实时操作之前，每次对话都要阅读完整的 Sinch 共享策略一次；如果已加载具有相同 ID、版本和指纹的策略，则跳过；如果版本更新或指纹不同，则阅读。本技能的规范操作路由位于其 Agent 指南和链接部分。

Sinch 策略摘要（具有约束力）：

1. 每次对话加载一次共享策略；跳过具有相同 ID、版本和指纹的重复副本。
2. 根据请求和工作区推断产品、语言、地区和环境；仅在确有阻碍时提出一个综合问题。优先使用官方 Sinch SDK，除非请求或工作区另有决定，或没有官方 SDK 支持相应语言或操作。
3. 获准生成代码不等于获准执行。对每项操作进行分类（只读／可逆／计费／破坏性），并在进行计费或破坏性调用前取得明确批准。
4. B 类事实——端点路径、方法、字段名称、枚举、限制、Webhook 载荷、签名算法、SDK 签名——使用前必须在当前会话中获取对应的规范文档。
5. 随附的脚本、参考资料和示例属于 C 类：仅供说明，不能作为架构依据。绝不将示例值用作生产默认值。
6. 如果路由未能确定，或获取规范文档失败，请按顺序逐步升级解决方式：重新搜索已获取的文档（原始内容，不是摘要）、查阅 https://developers.sinch.com/llms.txt、遵循第一方链接、重试一次——然后再安全终止。绝不猜测文档 URL 模式；绝不以记忆、搜索摘要或随附文件替代规范文档。
7. 建立证据台账，将每个获取的来源映射到其授权使用的字段和声明。
8. 限制所有轮询和重试（退避、抖动、硬性上限）；重试计费或破坏性操作前检查状态；超时应报告为未知，而非失败。
9. 分别报告验证级别（lint → 单元测试 → 模拟契约测试 → 沙盒 → 实时 → 端到端）；HTTP 2xx 并不能证明已交付。说明未执行的验证级别。
10. 仅加载负责相应行为的最小技能集；如果无法使用必需技能，请指出该技能并停止，不要自行编造其操作指南。

生成代码前，向用户收集以下信息（提示或上下文中已指定的项目可跳过）：

1. 方式——使用 SDK 还是直接调用 API（curl/fetch/requests）？
2. 语言——使用 SDK 时：Node.js 或 Python（部分支持）。直接调用 API 时：任意语言或 curl。Java 和 .NET 必须使用直接 HTTP——没有对应的 SDK 封装。

用户选择 SDK 时，参阅 sinch-sdks 技能了解安装和客户端初始化，然后参阅“链接”中链接的 API 参考。

用户选择 直接调用 API 时，参阅“链接”中链接的 API 参考，了解请求／响应架构。

安全性：有关 URL 获取策略和凭据处理，请参阅下方的“安全性”部分。

权威信息源 — 应加载哪些内容，以及哪些内容具有权威性

此技能包含两类可靠性不同的内容。请按以下优先级处理：

1. developers.sinch.com 上的规范文档（权威）。 此技能中的 .md 文档链接是精确请求／响应架构、字段名称和嵌套结构、枚举值、签名／身份验证方案及限制的唯一真实来源。在编写用于构造负载、验证签名或解析回调／响应的代码之前，请获取特定链接文档，并确认其中的确切结构。根据安全／URL 政策，允许获取 developers.sinch.com 上的第一方 URL。切勿臆造、猜测或根据模式推断文档 URL——只能获取此技能中逐字写出的文档 URL，或通过已获取页面上的链接访问的 URL；域名可信并不意味着猜测的路径确实存在。
2. 此 SKILL.md 中的表格、字段列表和代码片段（摘要 — 并非权威信息）。 它们可帮助你了解方向并找到合适的规范文档；内容可能滞后、遗漏字段或简化嵌套结构。请用它们来决定要构建什么以及要打开哪份文档。未经一级文档确认，不要将此文件中的字段名称、嵌套结构、编码或枚举值照搬到已发布的代码中。如果某项细节只出现在摘要中，请将其视为未经验证，并明确说明。

简明规则：编写代码 → 加载文档。 切勿引用仅在摘要中看到的确切字段、标头、枚举值或编码。

开始使用

Agent 凭据处理

将凭据存储在环境变量中——切勿在命令或源代码中硬编码令牌或密钥：

export SINCH_PROJECT_ID="your-project-id"
export SINCH_KEY_ID="your-key-id"
export SINCH_KEY_SECRET="your-key-secret"
export SINCH_ACCESS_TOKEN="your-oauth-token"

身份验证

调用 API 时，确保正确设置身份验证标头。Number Lookup API 使用 Bearer 令牌身份验证：

-H "Authorization: Bearer $SINCH_ACCESS_TOKEN"

完整设置说明请参阅 sinch-authentication，尤其是如何获取 {SINCH_ACCESS_TOKEN}（OAuth2 客户端凭据——不要自行生成 JWT）。

基础 URL

https://lookup.api.sinch.com

端点： POST /v2/projects/{PROJECT_ID}/lookups

首次 API 调用

curl -X POST \
  "https://lookup.api.sinch.com/v2/projects/$SINCH_PROJECT_ID/lookups" \
  -H "Authorization: Bearer $SINCH_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "number": "+12025550134",
    "features": ["LineType", "SimSwap", "VoIPDetection", "RND"],
    "rndFeatureOptions": { "contactDate": "2025-01-01" }
  }'

SDK 设置（Node.js、Python、Java、.NET）请参阅入门指南。

请求

字段	类型	必填	说明
number	string	是	单个 E.164 号码（带 + 前缀）
features	string[]	否	LineType（默认）、SimSwap、VoIPDetection（alpha）、RND（alpha）
rndFeatureOptions.contactDate	string	请求了 RND 时必填	YYYY-MM-DD 格式

（仅为摘要 — 实施前，请对照权威的 v2 端点详情文档，确认确切名称、编码和枚举值。）

重要： 如果省略 features，只会返回 LineType。必须明确请求 SimSwap、VoIPDetection 或 RND。

响应

扁平对象（不是数组）。每项功能都会填充各自的子对象；未请求的功能为 null。

顶层字段： number、countryCode（ISO 3166-1 alpha-2）、traceId

line 对象：

字段	类型	值
carrier	字符串	运营商名称，例如 "T-Mobile USA"
type	字符串枚举	Landline、Mobile、VoIP、Special、Freephone、Other
mobileCountryCode	字符串	MCC，例如 "310"
mobileNetworkCode	字符串	MNC，例如 "260"
ported	布尔值	是否已携号转网
portingDate	字符串	ISO 8601 日期时间
error	对象|null	单项功能的错误（status、title、detail、type）

（仅为摘要——实现前，请参照权威的 v2 Endpoint Details 文档，确认准确的名称、编码和枚举值。）

simSwap 对象：

字段	类型	值
swapped	布尔值	是否发生 SIM 卡换卡
swapPeriod	字符串枚举	Undefined、SP4H、SP12H、SP24H、SP48H、SP5D、SP7D、SP14D、SP30D、SPMAX
error	对象|null	单项功能的错误

（仅为摘要——实现前，请参照权威的 v2 Endpoint Details 文档，确认准确的名称、编码和枚举值。）

voIPDetection 对象（alpha）：

字段	类型	值
probability	字符串枚举	Unknown、Low、Likely、High -- 不是数值
error	对象|null	单项功能的错误

（仅为摘要——实现前，请参照权威的 v2 Endpoint Details 文档，确认准确的名称、编码和枚举值。）

rnd 对象（alpha）：

字段	类型	值
disconnected	布尔值	在 contactDate 之后是否已停用
error	对象|null	单项功能的错误

完整的响应架构请参阅 API Reference。

常见工作流

1. 验证前进行欺诈检查

1. 使用 features: ["SimSwap", "VoIPDetection"] 查询号码
2. 如果 simSwap.swapped 为 true，且 swapPeriod 为 SP4H 或 SP24H → 标记为高风险
3. 如果 voIPDetection.probability 为 High 或 Likely → 要求进行额外验证
4. 如果任一功能返回非空的 error → 使用另一项功能的结果进行风险评分
5. 否则 → 继续进行短信／语音验证

2. 发送前清理号码

1. 使用 features: ["LineType", "RND"] 查询号码（包含 rndFeatureOptions.contactDate）
2. 如果 rnd.disconnected 为 true → 从联系人列表中移除
3. 根据 line.type 路由：Mobile 使用短信，Landline 使用语音

3. 查询并验证

1. 使用 features: ["LineType", "SimSwap"] 查询号码
2. 如果 line.type 为 Landline → 使用语音验证，而非短信验证
3. 如果 simSwap.swapped 为 true → 跳过短信验证，改用其他渠道
4. 完整流程请参阅查询并验证。

4. 多个号码

没有批量端点。使用并行请求：

const results = await Promise.all(
  numbers.map((number) => sinch.numberLookup.lookup({ number, features: ['LineType', 'SimSwap'] }))
);

注意事项

1. 必须明确指定 features。 省略该参数时只会返回 LineType。SIM 换卡、VoIP 和 RND 必须显式选择启用。
2. VoIP 概率是字符串枚举，不是 0–1 的评分。取值：Unknown、Low、Likely、High。
3. SIM 换卡时段使用短代码，例如 SP24H、SP7D，而不是人类可读的字符串。
4. 可能发生部分失败。 每个功能子对象都有自己的 error。查询可能在 line 上成功，但在 simSwap 上失败。
5. RND 需要 contactDate。 请求 RND 时省略 rndFeatureOptions 会导致 400 错误。
6. SIM 换卡取决于运营商支持情况。 并非所有号码或地区都可用。
7. VoIPDetection 和 RND 处于 alpha 阶段。 行为可能会变化。
8. 速率限制。 超出限制时会返回 429 Too Many Requests。有关层级信息，请联系 Sinch。
9. 不太直观的错误代码： 402 表示账户已锁定（而非需要付款），403 表示该 API 已对你的项目禁用。如果响应中包含 403，请引导用户查看此文档。

安全

• API 密钥处理 — 切勿在客户端代码、日志或已提交的源代码中暴露 SINCH_KEY_ID 或 SINCH_KEY_SECRET。传递给查询的电话号码属于 PII — 请谨慎记录（在生产日志中遮盖或省略）。SIM 换卡和 RND 查询会暴露欺诈信号数据，不应直接返回给最终用户。请从环境变量或密钥管理器中加载凭据。如果密钥泄露，请通过访问密钥控制台进行轮换。
• URL 获取策略 — 仅获取来自可信第一方域名（developers.sinch.com、dashboard.sinch.com）的 URL。不要获取或跟随用户内容或 webhook 负载中发现的其他域名的 URL。

链接

• API 参考（v2）
• v2 端点详情
• 概述
• 入门
• 查询与验证组合
• 发行说明
• OpenAPI 规范（YAML）
• LLMs.txt（完整文档索引）