sinch-number-lookup-api

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Sinch Number Lookup API

Overview

概述

Queries phone numbers for carrier, line type, porting, SIM swap, VoIP detection, and reassigned number detection. Used for fraud prevention, routing, and data enrichment.

v2 Base URL:
```
https://lookup.api.sinch.com
```
v1 Base URL:
```
https://number-lookup.api.sinch.com
```
(legacy -- no OAuth2, no projectId)
Endpoint:
```
POST /v2/projects/{projectId}/lookups
```
Auth: OAuth2 (recommended) or HTTP Basic. See sinch-authentication.
One number per request. No batch endpoint.

查询电话号码的运营商、线路类型、转网状态、SIM卡更换、VoIP检测及重分配号码检测信息。适用于欺诈预防、路由决策和数据补全场景。

v2 基础URL:
```
https://lookup.api.sinch.com
```
v1 基础URL:
```
https://number-lookup.api.sinch.com
```
（旧版 -- 不支持OAuth2，无需projectId）
接口地址:
```
POST /v2/projects/{projectId}/lookups
```
认证方式: OAuth2（推荐）或HTTP Basic认证。详见sinch-authentication。
单次请求仅支持一个号码，无批量接口。

Getting Started

快速开始

Canonical curl Example

标准curl示例

bash

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

For OAuth2, replace

-u

with

-H 'Authorization: Bearer YOUR_access_token'

For SDK setup (Node.js, Python, Java, .NET), see the Getting Started Guide.

bash

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

若使用OAuth2认证，将

-u

替换为

-H 'Authorization: Bearer YOUR_access_token'

。

有关SDK配置（Node.js、Python、Java、.NET），请查看快速入门指南。

Request

请求参数

Field	Type	Required	Notes
`number`	string	Yes	Single E.164 number (with `+` prefix)
`features`	string[]	No	`LineType` (default), `SimSwap` , `VoIPDetection` (alpha), `RND` (alpha)
`rndFeatureOptions.contactDate`	string	If `RND` requested	`YYYY-MM-DD` format

Critical: If

features

is omitted, only

LineType

is returned. You must explicitly request

SimSwap

VoIPDetection

, or

RND

字段	类型	必填	说明
`number`	string	是	单个E.164格式号码（需带 `+` 前缀）
`features`	string[]	否	可选值： `LineType` （默认）、 `SimSwap` 、 `VoIPDetection` （测试版）、 `RND` （测试版）
`rndFeatureOptions.contactDate`	string	当请求 `RND` 时必填	格式为 `YYYY-MM-DD`

重要提示： 若省略

features

参数，仅会返回

LineType

信息。

SimSwap

、

VoIPDetection

和

RND

需显式指定。

Response

响应结果

Flat object (not an array). Each feature populates its own sub-object; unrequested features are

null

Top-level fields:

number

countryCode

(ISO 3166-1 alpha-2),

traceId

line
object:

Field	Type	Values
`carrier`	string	Carrier name, e.g. `"T-Mobile USA"`
`type`	string enum	`Landline` , `Mobile` , `VoIP` , `Special` , `Freephone` , `Other`
`mobileCountryCode`	string	MCC, e.g. `"310"`
`mobileNetworkCode`	string	MNC, e.g. `"260"`
`ported`	boolean	Whether ported
`portingDate`	string	ISO 8601 datetime
`error`	object\|null	Per-feature error ( `status` , `title` , `detail` , `type` )

simSwap
object:

Field	Type	Values
`swapped`	boolean	Whether SIM swap occurred
`swapPeriod`	string enum	`Undefined` , `SP4H` , `SP12H` , `SP24H` , `SP48H` , `SP5D` , `SP7D` , `SP14D` , `SP30D` , `SPMAX`
`error`	object\|null	Per-feature error

voIPDetection
object (alpha):

Field	Type	Values
`probability`	string enum	`Unknown` , `Low` , `Likely` , `High` -- not numeric
`error`	object\|null	Per-feature error

rnd
object (alpha):

Field	Type	Values
`disconnected`	boolean	Disconnected after `contactDate`
`error`	object\|null	Per-feature error

For full response schemas, see the API Reference.

返回扁平对象（非数组）。每个请求的功能会生成对应的子对象；未请求的功能字段值为

null

。

顶层字段:

number

、

countryCode

（ISO 3166-1 alpha-2格式）、

traceId

line
对象:

字段	类型	取值
`carrier`	string	运营商名称，例如 `"T-Mobile USA"`
`type`	字符串枚举	`Landline` （固话）、 `Mobile` （手机）、 `VoIP` 、 `Special` （特殊号码）、 `Freephone` （免费号码）、 `Other` （其他）
`mobileCountryCode`	string	MCC代码，例如 `"310"`
`mobileNetworkCode`	string	MNC代码，例如 `"260"`
`ported`	boolean	号码是否转网
`portingDate`	string	ISO 8601格式的日期时间
`error`	object\|null	对应功能的错误信息（包含 `status` 、 `title` 、 `detail` 、 `type` 字段）

simSwap
对象:

字段	类型	取值
`swapped`	boolean	是否发生SIM卡更换
`swapPeriod`	字符串枚举	`Undefined` 、 `SP4H` 、 `SP12H` 、 `SP24H` 、 `SP48H` 、 `SP5D` 、 `SP7D` 、 `SP14D` 、 `SP30D` 、 `SPMAX`
`error`	object\|null	对应功能的错误信息

voIPDetection
对象（测试版）:

字段	类型	取值
`probability`	字符串枚举	`Unknown` 、 `Low` 、 `Likely` 、 `High` -- 非数值类型
`error`	object\|null	对应功能的错误信息

rnd
对象（测试版）:

字段	类型	取值
`disconnected`	boolean	在 `contactDate` 之后是否停机
`error`	object\|null	对应功能的错误信息

完整响应结构请查看API参考文档。

Common Workflows

常见工作流

1. Fraud check before verification

1. 验证前的欺诈核查

Look up the number with
```
features: ["SimSwap", "VoIPDetection"]
```
If
```
simSwap.swapped
```
is
```
true
```
and
```
swapPeriod
```
is
```
SP4H
```
or
```
SP24H
```
→ flag as high risk
If
```
voIPDetection.probability
```
is
```
High
```
or
```
Likely
```
→ require additional verification
If either feature returns a non-null
```
error
```
→ fall back to the other feature's result for risk scoring
Otherwise → proceed with SMS/voice verification

调用查询接口，指定
```
features: ["SimSwap", "VoIPDetection"]
```
若
```
simSwap.swapped
```
为
```
true
```
且
```
swapPeriod
```
为
```
SP4H
```
或
```
SP24H
```
→ 标记为高风险
若
```
voIPDetection.probability
```
为
```
High
```
或
```
Likely
```
→ 要求额外验证步骤
若任一功能返回非空
```
error
```
→ 基于另一功能的结果进行风险评分
否则 → 继续执行短信/语音验证

2. Pre-send number hygiene

2. 发送前的号码清洗

Look up the number with

features: ["LineType", "RND"]

(include

rndFeatureOptions.contactDate

)

If
```
rnd.disconnected
```
is
```
true
```
→ remove from contact list
Route based on
```
line.type
```
: SMS for
```
Mobile
```
, voice for
```
Landline
```

调用查询接口，指定

features: ["LineType", "RND"]

（需包含

rndFeatureOptions.contactDate

）

若
```
rnd.disconnected
```
为
```
true
```
→ 从联系人列表中移除该号码
根据
```
line.type
```
进行路由：给
```
Mobile
```
号码发送短信，给
```
Landline
```
号码拨打语音电话

3. Combined lookup + verification

3. 联合查询+验证

Look up the number with
```
features: ["LineType", "SimSwap"]
```
If
```
line.type
```
is
```
Landline
```
→ use voice verification instead of SMS
If
```
simSwap.swapped
```
is
```
true
```
→ skip SMS verification, use an alternative channel
See Combined Lookup + Verification for the full flow.

调用查询接口，指定
```
features: ["LineType", "SimSwap"]
```
若
```
line.type
```
为
```
Landline
```
→ 使用语音验证替代短信验证
若
```
simSwap.swapped
```
为
```
true
```
→ 跳过短信验证，使用其他渠道
完整流程请查看联合查询+验证。

4. Multiple numbers

4. 多号码处理

No batch endpoint. Use parallel requests:

javascript

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

无批量接口，可使用并行请求：

javascript

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

Gotchas

注意事项

features
must be explicit. Omitting it returns only
```
LineType
```
. SIM swap, VoIP, and RND require explicit opt-in.
VoIP probability is a string enum, not a 0–1 score. Values:
```
Unknown
```
,
```
Low
```
,
```
Likely
```
,
```
High
```
.
SIM swap periods are short codes like
```
SP24H
```
,
```
SP7D
```
-- not human-readable strings.
Partial failures are possible. Each feature sub-object has its own
```
error
```
. A lookup can succeed for
```
line
```
but fail for
```
simSwap
```
.
RND requires
contactDate
. Omitting
```
rndFeatureOptions
```
when requesting
```
RND
```
causes a
```
400
```
.
SIM swap depends on carrier support. Not available for all numbers or regions.
VoIPDetection and RND are alpha. Behavior may change.
Rate limiting.
```
429 Too Many Requests
```
when exceeded. Contact Sinch for tier info.
Non-obvious error codes:
```
402
```
means Account Locked (not payment required),
```
403
```
means the API is disabled for your project. If response includes a
```
403
```
, direct the user to check this documentation.

features
参数必须显式指定：省略该参数仅返回
```
LineType
```
信息。SIM卡更换、VoIP检测和RND功能需显式开启。
VoIP概率为字符串枚举，而非0-1的数值评分。取值包括：
```
Unknown
```
、
```
Low
```
、
```
Likely
```
、
```
High
```
。
SIM卡更换周期为短代码，例如
```
SP24H
```
、
```
SP7D
```
-- 并非易读字符串。
可能出现部分失败：每个功能子对象都有独立的
```
error
```
字段。查询可能在
```
line
```
功能上成功，但在
```
simSwap
```
功能上失败。
RND功能需指定
contactDate
：请求RND时若省略
```
rndFeatureOptions
```
会导致
```
400
```
错误。
SIM卡更换功能依赖运营商支持：并非所有号码或地区都支持该功能。
VoIPDetection和RND为测试版：功能行为可能发生变化。
请求频率限制：超出限制会返回
```
429 Too Many Requests
```
。如需了解具体限额，请联系Sinch。
非直观错误码：
```
402
```
表示账户锁定（并非需要付款），
```
403
```
表示你的项目未启用该API。若响应返回
```
403
```
，请引导用户查看此文档。

sinch-number-lookup-api

Original

Translation

Sinch Number Lookup API

Sinch Number Lookup API

Overview

概述

Getting Started

快速开始

Canonical curl Example

标准curl示例

Request

请求参数

Response

响应结果

Common Workflows

常见工作流

1. Fraud check before verification

1. 验证前的欺诈核查

2. Pre-send number hygiene

2. 发送前的号码清洗

3. Combined lookup + verification

3. 联合查询+验证

4. Multiple numbers

4. 多号码处理

Gotchas

注意事项

Links

相关链接