sinch-imported-numbers-hosting-orders

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Sinch Imported Numbers & Hosting Orders

Sinch 导入号码与托管订单

Overview

概述

The Imported Numbers and Hosting Orders API imports non-Sinch phone numbers for use with Sinch SMS without porting. It manages the lifecycle from qualification through text-enablement, including LOA generation and carrier OSR updates.

Imported Numbers和Hosting Orders API无需号码转网，即可将非Sinch电话号码导入以用于Sinch SMS服务。它管理从号码验证到短信启用的全生命周期，包括LOA生成和运营商OSR更新。

Agent Instructions

Agent操作说明

Before generating code, ask the user these clarifying questions:

Goal — What do you need?
- Import a number (single or bulk)?
- Qualify numbers for text-enablement?
- Text-enable qualified numbers?
- Check status of an existing order?
LOA type (if text-enabling) — Are you a direct Sinch customer, a reseller, or do you have a blanket LOA?
Number type (if text-enabling) — Standard or Toll-Free?
Language — curl, Node.js SDK, Python, Java?

Wait for answers, then follow the matching workflow below.

生成代码前，请向用户询问以下澄清问题：

目标 — 你需要实现什么功能？
- 导入单个号码还是批量导入？
- 验证号码以启用短信功能？
- 为已验证号码启用短信功能？
- 检查现有订单状态？
LOA类型（若启用短信功能）— 你是Sinch直接客户、经销商，还是拥有通用LOA（blanket LOA）？
号码类型（若启用短信功能）— 标准号码还是免费电话（Toll-Free）？
开发语言/工具 — curl、Node.js SDK、Python还是Java？

等待用户回复后，遵循下方对应的工作流操作。

Decision Tree

决策树

User wants to work with imported numbers →
├─ Import numbers
│  ├─ Single number    → Workflow A (Import Number)
│  └─ Bulk (≤5)        → Workflow B (Bulk Import via Hosting Order)
├─ Qualify numbers     → Workflow C (Qualify → email invoices)
├─ Text-enable numbers
│  ├─ Standard numbers → Workflow D (Text-Enable)
│  └─ Toll-Free        → Workflow D variant (TF endpoint)
├─ Check order status  → Workflow E (Hosting Order Status)
└─ Manage numbers      → Workflow F (CRUD operations)

用户需要处理导入号码 →
├─ 导入号码
│  ├─ 单个号码    → 工作流A（导入单个号码）
│  └─ 批量（≤5个） → 工作流B（通过托管订单批量导入）
├─ 验证号码     → 工作流C（验证 → 发送发票邮件）
├─ 启用短信功能
│  ├─ 标准号码 → 工作流D（启用短信功能）
│  └─ 免费电话 → 工作流D变体（使用TF端点）
├─ 检查订单状态  → 工作流E（托管订单状态查询）
└─ 管理号码      → 工作流F（CRUD操作）

Critical Rules

重要规则

E.164 format required. All phone numbers must include leading
```
+
```
(e.g.,
```
+12025550134
```
).
Qualification requires manual review. After
```
addNumbers
```
, the user must email invoices to
```
orders@sinch.com
```
. Takes 1–3 business days.
Unlink before relinking. To change service plan or campaign, first set both to empty string
```
""
```
, then set new values in a separate request.
Hosting orders are async. Poll order status or set
```
callbackUrl
```
per-request.
List hosting orders requires all four params:
```
states
```
,
```
type
```
,
```
servicePlanId
```
,
```
campaignId
```
are all required.
migrateToSinchTmo
is read-only on responses. Exception: writable in
```
hostingOrders:importNumbers
```
requests.

必须使用E.164格式。所有电话号码必须以
```
+
```
开头（例如：
```
+12025550134
```
）。
号码验证需要人工审核。调用
```
addNumbers
```
后，用户必须将发票邮件发送至
```
orders@sinch.com
```
，审核需1-3个工作日。
重新关联前需先解绑。若要更改服务计划或活动，需先将两者设置为空字符串
```
""
```
，再通过单独请求设置新值。
托管订单为异步处理。可轮询订单状态，或在请求中设置
```
callbackUrl
```
。
查询托管订单列表需提供四个参数：
```
states
```
、
```
type
```
、
```
servicePlanId
```
、
```
campaignId
```
均为必填项。
migrateToSinchTmo
字段：在响应中为只读字段。例外情况：在
```
hostingOrders:importNumbers
```
请求中可写。

Getting Started

快速开始

Authentication

身份验证

See sinch-authentication for full auth setup. This API uses OAuth2 client credentials (production) or Basic Auth (testing only, rate-limited).

Base URL:

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

Region: US and CA only. Single global endpoint (not regionalized).

完整的身份验证设置请参考sinch-authentication。该API在生产环境使用OAuth2客户端凭证，测试环境仅支持基础认证（有调用频率限制）。

基础URL：

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

适用区域： 仅美国和加拿大。使用单一全球端点（无区域化区分）。

First API Call — Import a Number

首次API调用 — 导入单个号码

bash

curl -X POST "https://imported.numbers.api.sinch.com/v1/projects/{PROJECT_ID}/importedNumbers" \
  -H "Authorization: Bearer {ACCESS_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "phoneNumber": "+11234567890",
    "regionCode": "US",
    "displayName": "My Number",
    "smsConfiguration": {
      "servicePlanId": "YOUR_service_plan_id",
      "campaignId": "YOUR_campaign_id"
    },
    "callbackUrl": "https://example.com/callback"
  }'

bash

curl -X POST "https://imported.numbers.api.sinch.com/v1/projects/{PROJECT_ID}/importedNumbers" \
  -H "Authorization: Bearer {ACCESS_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "phoneNumber": "+11234567890",
    "regionCode": "US",
    "displayName": "My Number",
    "smsConfiguration": {
      "servicePlanId": "YOUR_service_plan_id",
      "campaignId": "YOUR_campaign_id"
    },
    "callbackUrl": "https://example.com/callback"
  }'

Key Concepts

核心概念

Imported Number — Non-Sinch number enabled for SMS via Sinch as DCA. Linked to a service plan and optionally a 10DLC campaign.

Qualified Number — Number that passed eligibility review. States:

ELIGIBLE_CHECK_PENDING

→

ELIGIBLE

NOT_ELIGIBLE

→

VERIFICATION_PENDING

→

VERIFIED

VERIFICATION_FAILED

VERIFICATION_BLOCKED

→

HOSTING_IN_PROGRESS

→

HOSTING_DONE

HOSTING_FAILED

Hosting Order — Async provisioning tracker. States:

DRAFT

→

SUBMITTED

→

WAITING_FOR_LOA_SIGNATURE

→

IN_PROGRESS

→

COMPLETED

REJECTED

. Type:

IMPORT

TYPE_TEXT_ENABLE

LOA — Letter of Authorization for text-enablement. Three types:
```
directLoaInfo
```
,
```
resellerLoaInfo
```
,
```
blanketLoaInfo
```
(empty
```
{}
```
).
Service Plan ID — Links number to SMS service. Campaign ID — Links to 10DLC campaign (US A2P).
OSR Update — Carrier-level record update. Schedulable via
```
scheduledOsrUpdateTime
```
.

导入号码 — 作为DCA通过Sinch启用SMS功能的非Sinch号码，关联至某个服务计划，可选关联10DLC活动。

已验证号码 — 通过资格审核的号码。状态流程：

ELIGIBLE_CHECK_PENDING

→

ELIGIBLE

NOT_ELIGIBLE

→

VERIFICATION_PENDING

→

VERIFIED

VERIFICATION_FAILED

VERIFICATION_BLOCKED

→

HOSTING_IN_PROGRESS

→

HOSTING_DONE

HOSTING_FAILED

。

托管订单 — 异步配置跟踪器。状态流程：

DRAFT

→

SUBMITTED

→

WAITING_FOR_LOA_SIGNATURE

→

IN_PROGRESS

→

COMPLETED

REJECTED

。类型分为

IMPORT

或

TYPE_TEXT_ENABLE

。

LOA — 用于启用短信功能的授权书（Letter of Authorization）。分为三种类型：
```
directLoaInfo
```
、
```
resellerLoaInfo
```
、
```
blanketLoaInfo
```
（值为
```
{}
```
）。
服务计划ID（Service Plan ID） — 将号码与SMS服务关联。活动ID（Campaign ID） — 关联至10DLC活动（美国A2P场景）。
OSR更新 — 运营商级记录更新，可通过
```
scheduledOsrUpdateTime
```
设置调度时间。

Workflows

工作流

Workflow A: Import Single Number

工作流A：导入单个号码

Ask for:

phoneNumber

regionCode

servicePlanId

. Optional:

campaignId

displayName

callbackUrl

1. Import number via
```
POST /importedNumbers
```
2. Verify:
```
GET /importedNumbers/{phoneNumber}
```

Numbers with their own NNID must complete NNID provisioning first.

API docs: Import number → Get imported number

需获取：

phoneNumber

、

regionCode

、

servicePlanId

。可选参数：

campaignId

、

displayName

、

callbackUrl

。

1. 调用
```
POST /importedNumbers
```
导入号码
2. 验证：调用
```
GET /importedNumbers/{phoneNumber}
```

自带NNID的号码需先完成NNID配置。

API文档：导入号码 → 查询导入号码

Workflow B: Bulk Import via Hosting Order

工作流B：通过托管订单批量导入

Ask for:

numbers

(list, max 5),

regionCode

servicePlanId

. Optional:

campaignId

callbackUrl

migrateToSinchTmo

1. Create hosting order via
```
POST /hostingOrders:importNumbers
```
2. Track:
```
GET /hostingOrders/{orderId}
```
— wait for
```
COMPLETED
```
3. Verify:
```
GET /hostingOrders/{orderId}/numbers
```
— check per-number status

Limit: 5 numbers per request by default. Contact account manager to increase.

API docs: Import numbers → Get order → List order numbers

需获取：

numbers

（号码列表，最多5个）、

regionCode

、

servicePlanId

。可选参数：

campaignId

、

callbackUrl

、

migrateToSinchTmo

。

1. 调用
```
POST /hostingOrders:importNumbers
```
创建托管订单
2. 跟踪状态：调用
```
GET /hostingOrders/{orderId}
```
— 等待状态变为
```
COMPLETED
```
3. 验证：调用
```
GET /hostingOrders/{orderId}/numbers
```
— 检查每个号码的状态

限制：默认每次请求最多导入5个号码。如需提升限制，请联系客户经理。

API文档：批量导入号码 → 查询订单 → 查询订单号码列表

Workflow C: Qualify Numbers

工作流C：验证号码

Ask for: list of

phoneNumbers

(E.164).

1. Submit batch via

POST /qualifiedNumbers:addNumbers

(body:

{"phoneNumbers": [...]}

)

2. Remind user: "Email invoices for these numbers to orders@sinch.com — qualification won't proceed without them."

3. Track:

GET /qualifiedNumbers/{phoneNumber}

— wait for

ELIGIBLE

state

4. If ownership verification required: run voice challenge (see Workflow F)

API docs: Create batch → Get qualified number

需获取：

phoneNumbers

列表（E.164格式）。

1. 调用

POST /qualifiedNumbers:addNumbers

提交批量验证请求（请求体：

{"phoneNumbers": [...]}

）

2. 提醒用户："请将这些号码的发票邮件发送至orders@sinch.com — 未发送发票将无法继续验证流程。"
3. 跟踪状态：调用
```
GET /qualifiedNumbers/{phoneNumber}
```
— 等待状态变为
```
ELIGIBLE
```
4. 若需所有权验证：执行语音验证挑战（见工作流F）

API文档：创建批量验证 → 查询已验证号码

Workflow D: Text-Enable Numbers

工作流D：启用短信功能

Ask for:

numbers

(list, max 500),

regionCode

servicePlanId

, and LOA info. Optional:

campaignId

nnid

scheduledOsrUpdateTime

callbackUrl

Determine LOA type:

Direct customer →
```
directLoaInfo
```
(authorized person, address, voice carrier)
Reseller →
```
resellerLoaInfo
```
(business name + authorized person, address, voice carrier)
Blanket LOA →
```
blanketLoaInfo: {}
```
(pre-approved with account manager)

1. Text-enable via

POST /qualifiedNumbers:textEnableNumbers

(or

POST /hostingOrders:textEnableNumbers

for full order response)

2. LOA sent to authorized person's email for e-signature — confirm email is correct before submitting
3. Track hosting order:
```
GET /hostingOrders/{orderId}
```

For Toll-Free, use

POST /qualifiedNumbers:textEnableTollFreeNumbers

POST /hostingOrders:textEnableTollFreeNumbers

instead.

API docs: Text-enable (qualified) · Text-enable (hosting order) · TF (qualified) · TF (hosting order)

需获取：

numbers

列表（最多500个）、

regionCode

、

servicePlanId

，以及LOA信息。可选参数：

campaignId

、

nnid

、

scheduledOsrUpdateTime

、

callbackUrl

。

确定LOA类型：

直接客户 → 使用
```
directLoaInfo
```
（需提供授权人、地址、语音运营商信息）
经销商 → 使用
```
resellerLoaInfo
```
（需提供企业名称+授权人、地址、语音运营商信息）
通用LOA → 使用
```
blanketLoaInfo: {}
```
（需提前与客户经理确认获批）

1. 调用

POST /qualifiedNumbers:textEnableNumbers

启用短信功能（或调用

POST /hostingOrders:textEnableNumbers

获取完整订单响应）

2. LOA将发送至授权人邮箱以进行电子签名 — 提交前请确认邮箱地址正确
3. 跟踪托管订单状态：调用
```
GET /hostingOrders/{orderId}
```

对于免费电话（Toll-Free），请使用

POST /qualifiedNumbers:textEnableTollFreeNumbers

或

POST /hostingOrders:textEnableTollFreeNumbers

替代。

API文档：启用短信功能（已验证号码） · 启用短信功能（托管订单） · 免费电话启用短信功能（已验证号码） · 免费电话启用短信功能（托管订单）

Workflow E: Check Hosting Order Status

工作流E：检查托管订单状态

1. List orders:

GET /hostingOrders?states=...&type=...&servicePlanId=...&campaignId=...

(all four required)

2. Get specific:
```
GET /hostingOrders/{orderId}
```
3. Get report:
```
GET /hostingOrders/{orderId}/report
```
(shows totals for OSR, SMS provisioned, campaign linked)
4. Drill into numbers:
```
GET /hostingOrders/{orderId}/numbers
```

API docs: List orders · Get order · Get report · List order numbers

1. 查询订单列表：调用

GET /hostingOrders?states=...&type=...&servicePlanId=...&campaignId=...

（四个参数均为必填）

2. 查询单个订单：调用
```
GET /hostingOrders/{orderId}
```
3. 获取订单报告：调用
```
GET /hostingOrders/{orderId}/report
```
（显示OSR、已配置SMS、关联活动的统计信息）
4. 查看订单详情号码：调用
```
GET /hostingOrders/{orderId}/numbers
```

API文档：查询订单列表 · 查询订单 · 获取订单报告 · 查询订单号码列表

Workflow F: Manage Numbers & Verification

工作流F：号码管理与验证

Imported numbers: list, get, update, delete via

/importedNumbers

and

/importedNumbers/{phoneNumber}

Qualified numbers: list (requires

states

param), get, delete via

/qualifiedNumbers

Voice challenge (ownership verification):

POST /qualifiedNumbers/{phone}:sendVoiceChallenge

— triggers voice call with code

POST /qualifiedNumbers/{phone}:verifyVoiceChallenge

— body:

{"code": "1234"}

API docs: List imported · Update imported · Delete imported · List qualified · Send challenge · Verify challenge

导入号码管理：通过

/importedNumbers

和

/importedNumbers/{phoneNumber}

接口执行列表查询、详情查询、更新、删除操作。

已验证号码管理：通过

/qualifiedNumbers

接口执行列表查询（需

states

参数）、详情查询、删除操作。

语音验证挑战（所有权验证）：

1. 调用

POST /qualifiedNumbers/{phone}:sendVoiceChallenge

— 触发语音呼叫并发送验证码

2. 调用

POST /qualifiedNumbers/{phone}:verifyVoiceChallenge

— 请求体：

{"code": "1234"}

API文档：查询导入号码列表 · 更新导入号码 · 删除导入号码 · 查询已验证号码列表 · 发送验证挑战 · 验证挑战码

Callbacks

回调

Callback URLs are set per-request via

callbackUrl

on import and text-enable operations (not project-level). Configure HMAC signing via

PATCH /callbackConfiguration

with

{"hmacSecret": "..."}

— verifies payloads via

X-Sinch-Signature

header.

See references/callbacks.md for full payload schema, event types, and failure codes.

Allowlist these IPs:

54.76.19.159

54.78.194.39

54.155.83.128

回调URL通过导入和启用短信功能请求中的

callbackUrl

参数按请求设置（非项目级全局设置）。可通过

PATCH /callbackConfiguration

接口配置HMAC签名，请求体为

{"hmacSecret": "..."}

— 通过

X-Sinch-Signature

头验证请求 payload。

完整的payload schema、事件类型和错误码请参考references/callbacks.md。

需将以下IP加入白名单：

54.76.19.159

54.78.194.39

54.155.83.128

Gotchas and Best Practices

注意事项与最佳实践

Bulk import limit:
```
hostingOrders:importNumbers
```
allows 5 numbers by default. Use
```
POST /importedNumbers
```
for single numbers.
Text-enable limit: Up to 500 numbers per request.
409 Conflict means the number is already imported. Check with
```
GET /importedNumbers/{phoneNumber}
```
first.

Hosting order states:

SUBMITTED

→

WAITING_FOR_LOA_SIGNATURE

→

IN_PROGRESS

→

COMPLETED

REJECTED

批量导入限制：
```
hostingOrders:importNumbers
```
默认最多支持5个号码。单个号码导入请使用
```
POST /importedNumbers
```
接口。
短信启用限制：每次请求最多支持500个号码。
409 Conflict错误表示该号码已被导入。请先调用
```
GET /importedNumbers/{phoneNumber}
```
查询确认。

托管订单状态流程：

SUBMITTED

→

WAITING_FOR_LOA_SIGNATURE

→

IN_PROGRESS

→

COMPLETED

REJECTED

。

sinch-imported-numbers-hosting-orders

Original

Translation

Sinch Imported Numbers & Hosting Orders

Sinch 导入号码与托管订单

Overview

概述

Agent Instructions

Agent操作说明

Decision Tree

决策树

Critical Rules

重要规则

Getting Started

快速开始

Authentication

身份验证

First API Call — Import a Number

首次API调用 — 导入单个号码

Key Concepts

核心概念

Workflows

工作流

Workflow A: Import Single Number

工作流A：导入单个号码

Workflow B: Bulk Import via Hosting Order

工作流B：通过托管订单批量导入

Workflow C: Qualify Numbers

工作流C：验证号码

Workflow D: Text-Enable Numbers

工作流D：启用短信功能

Workflow E: Check Hosting Order Status

工作流E：检查托管订单状态

Workflow F: Manage Numbers & Verification

工作流F：号码管理与验证

Callbacks

回调

Gotchas and Best Practices

注意事项与最佳实践

Links

相关链接