sinch-number-order-api

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Number Order API

Order phone numbers with KYC compliance through a guided multi-step workflow. Required in countries where number purchases need identity verification.

通过引导式多步骤工作流订购符合KYC合规要求的电话号码。在需要身份验证才能购买号码的国家/地区是必填流程。

Agent Instructions

Agent操作说明

This is a sequential, fragile workflow — steps must be followed in order. Do not combine API calls. Step 2 may be skipped if the user already has a specific E.164 number.

Before starting, collect from the user:

Country — ISO 3166-1 alpha-2 region code (e.g.
```
AU
```
,
```
DE
```
,
```
BR
```
)
Number type —
```
MOBILE
```
,
```
LOCAL
```
, or
```
TOLL_FREE
```
Specific number or quantity? — E.164 phone number, or quantity + criteria
SMS or Voice?
- SMS → needs
```
servicePlanId
```
  (+
```
campaignId
```
  for US 10DLC)
- Voice → needs
```
type
```
  (
```
RTC
```
  /
```
EST
```
  /
```
FAX
```
  ) + corresponding ID (
```
appId
```
  /
```
trunkId
```
  /
```
serviceId
```
  )

For authentication setup, see the authentication skill.

这是一个顺序执行、易出错的工作流——必须按步骤执行，不要合并API调用。如果用户已经有特定的E.164号码，可以跳过步骤2。

开始前，需向用户收集以下信息：

国家/地区 — ISO 3166-1 alpha-2地区代码（例如
```
AU
```
、
```
DE
```
、
```
BR
```
）
号码类型 —
```
MOBILE
```
、
```
LOCAL
```
或
```
TOLL_FREE
```
特定号码还是数量？ — E.164格式电话号码，或者数量+筛选条件
用于SMS还是Voice？
- SMS → 需要
```
servicePlanId
```
  （美国10DLC还需
```
campaignId
```
  ）
- Voice → 需要
```
type
```
  （
```
RTC
```
  /
```
EST
```
  /
```
FAX
```
  ）+ 对应的ID（
```
appId
```
  /
```
trunkId
```
  /
```
serviceId
```
  ）

关于认证设置，请查看认证技能。

Workflow

工作流

Execute in order. Report state to the user after each step.

Step 1 — Lookup requirements:

POST /v1/projects/{projectId}/numberOrders:lookupNumberRequirements

with

regionCode

numberType

. Save the response — it defines KYC

fields

schema and

attachments

(with

id

mandatory

allowedMimeTypes

allowedDocumentTypes

). Tell the user what's needed.

Step 2 — Search available numbers (skip if user has a specific number):
```
GET /v1/projects/{projectId}/availableNumbers?regionCode=XX&type=YY
```
. Optional filters:
```
capabilities
```
,
```
numberPattern.pattern
```
,
```
numberPattern.searchPattern
```
,
```
size
```
. Present results and let user choose.

Step 3 — Create order:

POST /v1/projects/{projectId}/numberOrders:createNumberOrder

. Use

numberOrderOption

(specific phones) or

quantityOrderOption

(criteria-based) — never both. Save

idNumberOrder

and

expireTime

from response.

Step 4 — Submit registration:

PUT /v1/projects/{projectId}/numberOrders/{numberOrderId}/registration

. Populate

requestDetails.data

using the schema from Step 1. Returns 400 on validation errors — fix and retry. Use

GET /v1/projects/{projectId}/numberOrders/{numberOrderId}/registration

to review.

Step 5 — Upload attachments (if Step 1 returned mandatory attachments):

POST /v1/projects/{projectId}/numberOrders/{numberOrderId}/attachments/{attachmentId}

multipart/form-data

. Check

allowedMimeTypes

before uploading.

Step 6 — Submit order:

POST /v1/projects/{projectId}/numberOrders/{numberOrderId}/submit

. State becomes

IN_REVIEW

The 48-hour clock starts at Step 3. Steps 4–6 must complete before the order expires.

Check status anytime:

GET /v1/projects/{projectId}/numberOrders/{numberOrderId}

按顺序执行，每一步完成后向用户报告状态。

步骤1 — 查询要求：调用
```
POST /v1/projects/{projectId}/numberOrders:lookupNumberRequirements
```
，参数为
```
regionCode
```
+
```
numberType
```
。保存响应结果——它定义了KYC的
```
fields
```
schema和
```
attachments
```
（包含
```
id
```
、
```
mandatory
```
、
```
allowedMimeTypes
```
、
```
allowedDocumentTypes
```
）。告知用户所需的材料。
步骤2 — 搜索可用号码（如果用户已有特定号码则跳过）：调用
```
GET /v1/projects/{projectId}/availableNumbers?regionCode=XX&type=YY
```
。可选筛选条件：
```
capabilities
```
、
```
numberPattern.pattern
```
、
```
numberPattern.searchPattern
```
、
```
size
```
。展示结果并让用户选择。
步骤3 — 创建订单：调用
```
POST /v1/projects/{projectId}/numberOrders:createNumberOrder
```
。使用
```
numberOrderOption
```
（特定号码）或
```
quantityOrderOption
```
（基于条件）——切勿同时使用。保存响应中的
```
idNumberOrder
```
和
```
expireTime
```
。
步骤4 — 提交注册信息：调用
```
PUT /v1/projects/{projectId}/numberOrders/{numberOrderId}/registration
```
。使用步骤1返回的schema填充
```
requestDetails.data
```
。如果返回400错误（验证失败），修正后重试。可调用
```
GET /v1/projects/{projectId}/numberOrders/{numberOrderId}/registration
```
查看信息。

步骤5 — 上传附件（如果步骤1返回必填附件）：以

multipart/form-data

格式调用

POST /v1/projects/{projectId}/numberOrders/{numberOrderId}/attachments/{attachmentId}

。上传前检查

allowedMimeTypes

。

步骤6 — 提交订单：调用

POST /v1/projects/{projectId}/numberOrders/{numberOrderId}/submit

。状态变为

IN_REVIEW

。

48小时倒计时从步骤3开始。必须在订单过期前完成步骤4-6。

可随时调用以下接口检查状态：

GET /v1/projects/{projectId}/numberOrders/{numberOrderId}

Order States

订单状态

CREATED

→

IN_REVIEW

→

COMPLETED

REJECTED

EXPIRED

BLOCKED

NUMBER_ORDER_STATE_UNSPECIFIED

CREATED

→

IN_REVIEW

→

COMPLETED

REJECTED

EXPIRED

BLOCKED

NUMBER_ORDER_STATE_UNSPECIFIED

Canonical Example — Lookup Requirements (Step 1)

标准示例 — 查询要求（步骤1）

Base URL:

https://numbers.api.sinch.com

. Auth: Basic (Key ID : Key Secret) or OAuth2 bearer.

bash

curl -X POST \
  -u {KEY_ID}:{KEY_SECRET} \
  "https://numbers.api.sinch.com/v1/projects/{PROJECT_ID}/numberOrders:lookupNumberRequirements" \
  -H 'Content-Type: application/json' \
  -d '{"regionCode": "AU", "numberType": "MOBILE"}'

For all other endpoints, request/response schemas, and field-level details, see the Number Order API Reference.

基础URL：

https://numbers.api.sinch.com

。认证方式：Basic认证（Key ID : Key Secret）或OAuth2 bearer令牌。

bash

curl -X POST \
  -u {KEY_ID}:{KEY_SECRET} \
  "https://numbers.api.sinch.com/v1/projects/{PROJECT_ID}/numberOrders:lookupNumberRequirements" \
  -H 'Content-Type: application/json' \
  -d '{"regionCode": "AU", "numberType": "MOBILE"}'

所有其他接口的请求/响应schema、字段级详情，请查看Number Order API参考文档。

Error Recovery

错误恢复

Step 3 fails (number unavailable) — go back to Step 2, pick a different number, and retry Step 3.
Step 4 returns 400 — read the error response, fix the
```
data
```
fields, and PUT again. No need to recreate the order.
Order expires — start over from Step 1. The
```
idNumberOrder
```
is no longer valid.
Order rejected — check the rejection reason in the GET response, correct KYC data, and create a new order.

步骤3失败（号码不可用） — 返回步骤2，选择其他号码，并重试步骤3。
步骤4返回400错误 — 阅读错误响应，修正
```
data
```
字段，然后重新调用PUT接口。无需重新创建订单。
订单过期 — 从步骤1重新开始。
```
idNumberOrder
```
不再有效。
订单被拒绝 — 查看GET响应中的拒绝原因，修正KYC数据，然后创建新订单。

Gotchas

注意事项

48-hour expiry — reservation starts at order creation (Step 3), not at submission.
Country-specific KYC — the
```
data
```
schema varies per country. Always use Step 1 output — never hardcode.
Attachments are conditional — only required when Step 1 says
```
mandatory: true
```
.
Registration validation is synchronous — Step 4 returns 400 immediately on bad data.
E.164 required — phone numbers must include the
```
+
```
prefix.
Auth is Key ID / Key Secret — not the project ID.
callbackUrl
— optional on order creation. Allowlist IPs:
```
54.76.19.159
```
,
```
54.78.194.39
```
,
```
54.155.83.128
```
.

48小时过期规则 — 号码保留从订单创建（步骤3）开始，而非提交时。
国家/地区特定KYC要求 —
```
data
```
schema因国家/地区而异。务必使用步骤1的输出结果——切勿硬编码。
附件为条件必填 — 仅当步骤1返回
```
mandatory: true
```
时才需要上传。
注册验证为同步 — 步骤4若数据有误，会立即返回400错误。
必须使用E.164格式 — 电话号码必须包含
```
+
```
前缀。
认证使用Key ID / Key Secret — 而非项目ID。
callbackUrl
— 订单创建时可选。需将以下IP加入白名单：
```
54.76.19.159
```
、
```
54.78.194.39
```
、
```
54.155.83.128
```
。

sinch-number-order-api

Original

Translation

Number Order API

Number Order API

Agent Instructions

Agent操作说明

Workflow

工作流

Order States

订单状态

Canonical Example — Lookup Requirements (Step 1)

标准示例 — 查询要求（步骤1）

Error Recovery

错误恢复

Gotchas

注意事项

Links

相关链接