sinch-numbers-api

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Sinch Numbers API

The Numbers API lets you search, activate, manage, and release phone numbers — the prerequisite for SMS, Voice, and Conversation APIs.

Numbers API可让您搜索、激活、管理和释放电话号码——这是使用SMS、Voice和Conversation API的前提条件。

Instructions

操作步骤

Step 1: Choose approach

步骤1：选择实现方式

SDK project? Default to SDK if
```
@sinch/sdk-core
```
(Node),
```
sinch
```
(Python), or
```
com.sinch.sdk
```
(Java) is present.
Direct HTTP? Use curl/fetch with Basic auth.

For SDK code, read the correct reference before generating any code:

Language	Reference	SDK docs
TypeScript/Node.js	references/typescript.md	Syntax reference
Python	references/python.md	Syntax reference
Java	references/java.md	Syntax reference

For direct HTTP calls, see Numbers API Reference.

使用SDK项目？ 如果项目中已存在
```
@sinch/sdk-core
```
（Node.js）、
```
sinch
```
（Python）或
```
com.sinch.sdk
```
（Java），默认使用SDK。
直接调用HTTP？ 使用curl/fetch并结合Basic auth进行调用。

在生成任何代码前，请先阅读对应语言的SDK参考文档：

语言	参考文档	SDK文档
TypeScript/Node.js	references/typescript.md	语法参考
Python	references/python.md	语法参考
Java	references/java.md	语法参考

如果是直接调用HTTP，请查看Numbers API参考文档。

Step 2: Authenticate

步骤2：身份验证

See sinch-authentication for full setup. Use Basic auth (

-u KEY_ID:KEY_SECRET

) for quick starts, OAuth2 for production.

完整设置请查看sinch-authentication。快速入门可使用Basic auth（

-u KEY_ID:KEY_SECRET

），生产环境建议使用OAuth2。

Step 3: Verify connectivity

步骤3：验证连通性

bash

curl -X GET "https://numbers.api.sinch.com/v1/projects/{PROJECT_ID}/activeNumbers?regionCode=US&type=LOCAL&pageSize=10" \
  -u {KEY_ID}:{KEY_SECRET}

A 200 response confirms credentials and project access.

bash

curl -X GET "https://numbers.api.sinch.com/v1/projects/{PROJECT_ID}/activeNumbers?regionCode=US&type=LOCAL&pageSize=10" \
  -u {KEY_ID}:{KEY_SECRET}

返回200状态码即表示凭证和项目访问权限验证通过。

Workflows

工作流

Search and rent a number

搜索并租赁号码

```
GET /availableRegions
```
— discover valid
```
regionCode
```
values

GET /availableNumbers?regionCode={code}&type={type}

— search (both params required)

Pick a number →

POST /availableNumbers/{phoneNumber}:rent

with config body

```
GET /activeNumbers/{phoneNumber}
```
— confirm activation

Use

POST /availableNumbers:rentAny

to skip step 3 (US LOCAL numbers only).

```
GET /availableRegions
```
—— 获取有效的
```
regionCode
```
值

GET /availableNumbers?regionCode={code}&type={type}

—— 搜索号码（两个参数必填）

选择一个号码 → 携带配置体调用
```
POST /availableNumbers/{phoneNumber}:rent
```
```
GET /activeNumbers/{phoneNumber}
```
—— 确认号码已激活

对于美国本地号码，可使用

POST /availableNumbers:rentAny

跳过步骤3。

Safe retries for billable operations

计费操作的安全重试机制

Before retrying any potentially billable action (for example

:rent

:rentAny

, or

:release

) after an incomplete/uncertain response:

Check current state first using a read endpoint (
```
GET /activeNumbers/{phoneNumber}
```
or
```
GET /activeNumbers
```
with filters)
Retry only if the verification shows the prior action did not succeed
If state is ambiguous, prefer listing active numbers and matching on
```
phoneNumber
```
before issuing another billable request

在对可能产生计费的操作（例如

:rent

、

:rentAny

或

:release

）收到不完整/不确定的响应后进行重试前：

先通过只读端点（
```
GET /activeNumbers/{phoneNumber}
```
或带筛选条件的
```
GET /activeNumbers
```
）检查当前状态
仅当验证显示之前的操作未成功时再进行重试
如果状态不明确，建议先列出所有活跃号码并匹配
```
phoneNumber
```
，再发起新的计费请求

Update number configuration

更新号码配置

```
GET /activeNumbers/{phoneNumber}
```
— check current config

PATCH /activeNumbers/{phoneNumber}

— set

displayName

smsConfiguration

, or

voiceConfiguration

To unlink, send empty string
```
""
```
in
```
servicePlanId
```
or
```
campaignId
```

```
GET /activeNumbers/{phoneNumber}
```
—— 查看当前配置

PATCH /activeNumbers/{phoneNumber}

—— 设置

displayName

、

smsConfiguration

或

voiceConfiguration

如需解除关联，在
```
servicePlanId
```
或
```
campaignId
```
中传入空字符串
```
""
```

Release a number

释放号码

POST /activeNumbers/{phoneNumber}:release

调用

POST /activeNumbers/{phoneNumber}:release

Fetch all numbers to JSON

将所有号码导出为JSON

Run

node scripts/get_numbers.cjs --output numbers.json

(uses

SINCH_PROJECT_ID

SINCH_KEY_ID

SINCH_KEY_SECRET

env vars). Supports

--region

and

--type

filters.

运行

node scripts/get_numbers.cjs --output numbers.json

（使用环境变量

SINCH_PROJECT_ID

、

SINCH_KEY_ID

、

SINCH_KEY_SECRET

）。支持

--region

和

--type

筛选条件。

Emergency addresses

紧急地址

Use the emergency address endpoints on active numbers:

GET

provision

deprovision

validate

. See API reference.

使用活跃号码的紧急地址端点：

GET

、

provision

、

deprovision

、

validate

。详情请查看API参考文档。

Number orders (KYC-regulated regions)

号码订单（受KYC监管的区域）

Use the

numberOrders

endpoints:

lookupNumberRequirements

→

createNumberOrder

→ upload registration/attachments →

submit

. See API reference.

使用

numberOrders

端点：

lookupNumberRequirements

→

createNumberOrder

→ 上传注册资料/附件 →

submit

。详情请查看API参考文档。

Imported numbers

导入号码

A separate API at

https://imported.numbers.api.sinch.com

handles importing non-Sinch numbers (DCA) and hosting orders. See API reference.

独立API地址

https://imported.numbers.api.sinch.com

用于处理非Sinch号码（DCA）的导入和托管订单。详情请查看API参考文档。

Gotchas

注意事项

Param names differ between endpoints:
```
GET /activeNumbers
```
uses
```
capability
```
(singular) and
```
pageSize
```
.
```
GET /availableNumbers
```
uses
```
capabilities
```
(plural) and
```
size
```
(single page, no pagination).
type
defaults to
MOBILE
— omitting it returns only MOBILE numbers, not all types.
Always set
pageSize
explicitly on
```
GET /activeNumbers
```
— no documented default.
rentAny
is US LOCAL only — use
```
:rent
```
for other types/regions.
Do not blindly retry billable actions — if output is incomplete, verify state via
```
GET /activeNumbers/{phoneNumber}
```
(or list + filter) before retrying
```
:rent
```
,
```
:rentAny
```
, or
```
:release
```
.
Never pass both config objects unnecessarily — sending empty
```
voiceConfiguration
```
when you only need SMS will error.
Unlink before relinking — a number must be detached from its current service/campaign before attaching to a new one.
campaignId
is US-only — required for 10DLC, irrelevant elsewhere.

scheduledProvisioning
/
scheduledVoiceProvisioning
are objects (with

status

lastUpdatedTime

errorCodes

), not strings. Status values:

PROVISIONING_STATUS_UNSPECIFIED

WAITING

IN_PROGRESS

FAILED

voiceConfiguration
is a discriminated union on

type

RTC

→

appId

EST

→

trunkId

FAX

→

serviceId

Callback config (
```
PATCH /callbackConfiguration
```
) sets only
```
hmacSecret
```
for HMAC-SHA1 signature verification — it does not set a callback URL.
Callback IP allowlist:
```
54.76.19.159
```
,
```
54.78.194.39
```
,
```
54.155.83.128
```
.

端点间参数名称不同：
```
GET /activeNumbers
```
使用
```
capability
```
（单数）和
```
pageSize
```
；
```
GET /availableNumbers
```
使用
```
capabilities
```
（复数）和
```
size
```
（单页，无分页）。
type
默认值为
MOBILE
—— 省略该参数将仅返回移动号码，而非所有类型。
GET /activeNumbers
需显式设置
pageSize
—— 官方文档未说明默认值。
rentAny
仅适用于美国本地号码 —— 其他类型/区域请使用
```
:rent
```
。
请勿盲目重试计费操作 —— 如果输出不完整，在重试
```
:rent
```
、
```
:rentAny
```
或
```
:release
```
前，请先通过
```
GET /activeNumbers/{phoneNumber}
```
（或列表+筛选）验证状态。
请勿不必要地同时传递两个配置对象 —— 仅需SMS时发送空的
```
voiceConfiguration
```
会导致错误。
解除关联后再重新关联 —— 号码必须先与当前服务/活动解除关联，才能绑定到新的服务/活动。
campaignId
仅适用于美国 —— 10DLC要求必填，其他区域无需设置。

scheduledProvisioning
/
scheduledVoiceProvisioning
是对象（包含

status

、

lastUpdatedTime

、

errorCodes

），而非字符串。状态值包括：

PROVISIONING_STATUS_UNSPECIFIED

、

WAITING

、

IN_PROGRESS

、

FAILED

。

voiceConfiguration
是基于
type
的区分联合类型：
```
RTC
```
对应
```
appId
```
，
```
EST
```
对应
```
trunkId
```
，
```
FAX
```
对应
```
serviceId
```
。
回调配置（
```
PATCH /callbackConfiguration
```
）仅设置用于HMAC-SHA1签名验证的
```
hmacSecret
```
—— 不设置回调URL。
回调IP白名单：
```
54.76.19.159
```
、
```
54.78.194.39
```
、
```
54.155.83.128
```
。

sinch-numbers-api

Original

Translation

Sinch Numbers API

Sinch Numbers API

Instructions

操作步骤

Step 1: Choose approach

步骤1：选择实现方式

Step 2: Authenticate

步骤2：身份验证

Step 3: Verify connectivity

步骤3：验证连通性

Workflows

工作流

Search and rent a number

搜索并租赁号码

Safe retries for billable operations

计费操作的安全重试机制

Update number configuration

更新号码配置

Release a number

释放号码

Fetch all numbers to JSON

将所有号码导出为JSON

Emergency addresses

紧急地址

Number orders (KYC-regulated regions)

号码订单（受KYC监管的区域）

Imported numbers

导入号码

Gotchas

注意事项

Links

链接