sinch-porting-api
Compare original and translation side by side
🇺🇸
Original
English🇨🇳
Translation
ChineseSinch Porting API
Sinch Porting API
Overview
概述
The Porting API automates port-in operations — transferring phone numbers from another carrier into Sinch. It supports portability checks, order creation and management, document uploads, on-demand activation, and webhook notifications for status updates. Currently supports North American (US/CA) numbers only.
Porting API可自动化处理携号转入操作——将电话号码从其他运营商转移至Sinch。它支持可携性检查、订单创建与管理、文档上传、按需激活以及用于状态更新的Webhook通知。目前仅支持北美(美国/加拿大)号码。
Instructions
使用说明
Before generating code, gather from the user:
- Approach — SDK or direct API calls (curl/fetch)?
- Use case — Portability check, create order, track order, activate numbers?
- Activation mode (only for create order) — Automatic (on ) or on-demand (
desiredPortDate)?onDemandActivation: true
Note: The Node.js SDK does not currently have dedicated porting methods. Use direct HTTP calls for all porting operations.
@sinch/sdk-core在生成代码之前,需向用户收集以下信息:
- 实现方式——使用SDK还是直接调用API(curl/fetch)?
- 使用场景——可携性检查、创建订单、跟踪订单、激活号码?
- 激活模式(仅创建订单时需要)——自动激活(在日期)还是按需激活(
desiredPortDate)?onDemandActivation: true
注意: Node.js SDK目前没有专门的携号转方法。所有携号转操作均需使用直接HTTP调用。
@sinch/sdk-coreGetting Started
快速开始
Authentication
身份验证
See sinch-authentication for full setup.
完整设置请参考sinch-authentication。
Base URL
基础URL
| Environment | URL |
|---|---|
| Production | |
Store credentials in environment variables — never hardcode tokens, PINs, or keys in commands or source code:
bash
export PROJECT_ID="your-project-id"
export ACCESS_TOKEN="your-oauth-token"| 环境 | URL |
|---|---|
| 生产环境 | |
将凭证存储在环境变量中——切勿在命令或源代码中硬编码令牌、PIN码或密钥:
bash
export PROJECT_ID="your-project-id"
export ACCESS_TOKEN="your-oauth-token"First API Call — Check Portability
首次API调用——检查可携性
Always check portability before creating an order:
bash
curl -X POST "https://porting.api.sinch.com/v1/projects/$PROJECT_ID/portabilityChecks" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $ACCESS_TOKEN" \
-d '{
"phoneNumbers": ["+15551234567", "+15559876543"]
}'Response:
json
{
"phoneNumbers": [
{
"phoneNumber": "+15551234567",
"portable": true,
"carrier": "T-Mobile"
},
{
"phoneNumber": "+15559876543",
"portable": false,
"carrier": "Verizon",
"reason": "Number is not portable"
}
]
}创建订单前务必先检查号码可携性:
bash
curl -X POST "https://porting.api.sinch.com/v1/projects/$PROJECT_ID/portabilityChecks" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $ACCESS_TOKEN" \
-d '{
"phoneNumbers": ["+15551234567", "+15559876543"]
}'响应:
json
{
"phoneNumbers": [
{
"phoneNumber": "+15551234567",
"portable": true,
"carrier": "T-Mobile"
},
{
"phoneNumber": "+15559876543",
"portable": false,
"carrier": "Verizon",
"reason": "Number is not portable"
}
]
}Create a Port-In Order
创建携号转入订单
bash
curl -X POST "https://porting.api.sinch.com/v1/projects/$PROJECT_ID/orders/portIns" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $ACCESS_TOKEN" \
-d '{
"desiredPortSchedule": {
"desiredPortDate": "2026-05-15",
"desiredPortTime": "09:00:00",
"desiredPortTimeZone": "US/Eastern"
},
"customerOrderReference": "my-ref-123",
"phoneNumbers": [
{
"phoneNumber": "+15551234567",
"endUser": {
"name": "Acme Corp",
"streetNum": "123",
"streetName": "Main",
"streetType": "St",
"city": "Anytown",
"state": "CA",
"zipCode": "90210",
"typeOfService": "B"
},
"portOutInfo": {
"existingPortOutPin": "1234"
}
}
]
}'— Obtain this PIN from the losing carrier before submitting the order. See Create Port-In Order for full field reference.existingPortOutPin
Response:
json
{
"id": 12345,
"status": "PENDING",
"customerOrderReference": "my-ref-123",
"desiredPortSchedule": {
"desiredPortDate": "2026-05-15",
"desiredPortTime": "09:00:00",
"desiredPortTimeZone": "US/Eastern"
},
"phoneNumbers": [
{
"phoneNumber": "+15551234567",
"status": "PENDING"
}
]
}bash
curl -X POST "https://porting.api.sinch.com/v1/projects/$PROJECT_ID/orders/portIns" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $ACCESS_TOKEN" \
-d '{
"desiredPortSchedule": {
"desiredPortDate": "2026-05-15",
"desiredPortTime": "09:00:00",
"desiredPortTimeZone": "US/Eastern"
},
"customerOrderReference": "my-ref-123",
"phoneNumbers": [
{
"phoneNumber": "+15551234567",
"endUser": {
"name": "Acme Corp",
"streetNum": "123",
"streetName": "Main",
"streetType": "St",
"city": "Anytown",
"state": "CA",
"zipCode": "90210",
"typeOfService": "B"
},
"portOutInfo": {
"existingPortOutPin": "1234"
}
}
]
}'— 提交订单前需从原运营商获取此PIN码。完整字段参考请查看Create Port-In Order。existingPortOutPin
响应:
json
{
"id": 12345,
"status": "PENDING",
"customerOrderReference": "my-ref-123",
"desiredPortSchedule": {
"desiredPortDate": "2026-05-15",
"desiredPortTime": "09:00:00",
"desiredPortTimeZone": "US/Eastern"
},
"phoneNumbers": [
{
"phoneNumber": "+15551234567",
"status": "PENDING"
}
]
}Track an Order
跟踪订单
bash
undefinedbash
undefinedAuth: same Bearer token header as above
身份验证:使用与上述相同的Bearer令牌请求头
curl "https://porting.api.sinch.com/v1/projects/$PROJECT_ID/orders/portIns/12345"
-H "Authorization: Bearer $ACCESS_TOKEN"
-H "Authorization: Bearer $ACCESS_TOKEN"
Response:
```json
{
"id": 12345,
"status": "CONFIRMED",
"customerOrderReference": "my-ref-123",
"desiredPortSchedule": {
"desiredPortDate": "2026-05-15",
"desiredPortTime": "09:00:00",
"desiredPortTimeZone": "US/Eastern"
},
"phoneNumbers": [
{
"phoneNumber": "+15551234567",
"status": "CONFIRMED",
"focDate": "2026-05-15"
}
]
}curl "https://porting.api.sinch.com/v1/projects/$PROJECT_ID/orders/portIns/12345"
-H "Authorization: Bearer $ACCESS_TOKEN"
-H "Authorization: Bearer $ACCESS_TOKEN"
响应:
```json
{
"id": 12345,
"status": "CONFIRMED",
"customerOrderReference": "my-ref-123",
"desiredPortSchedule": {
"desiredPortDate": "2026-05-15",
"desiredPortTime": "09:00:00",
"desiredPortTimeZone": "US/Eastern"
},
"phoneNumbers": [
{
"phoneNumber": "+15551234567",
"status": "CONFIRMED",
"focDate": "2026-05-15"
}
]
}Activate Numbers (On-Demand)
激活号码(按需激活)
First check which number groups are ready:
bash
undefined首先检查哪些号码组已准备就绪:
bash
undefinedAuth: same Bearer token header as above
身份验证:使用与上述相同的Bearer令牌请求头
curl "https://porting.api.sinch.com/v1/projects/$PROJECT_ID/orders/portIns/12345/availableActivations"
-H "Authorization: Bearer $ACCESS_TOKEN"
-H "Authorization: Bearer $ACCESS_TOKEN"
Response:
```json
{
"activationGroups": [
{
"groupId": "grp-001",
"phoneNumbers": ["+15551234567"],
"status": "READY"
}
]
}Then activate:
bash
undefinedcurl "https://porting.api.sinch.com/v1/projects/$PROJECT_ID/orders/portIns/12345/availableActivations"
-H "Authorization: Bearer $ACCESS_TOKEN"
-H "Authorization: Bearer $ACCESS_TOKEN"
响应:
```json
{
"activationGroups": [
{
"groupId": "grp-001",
"phoneNumbers": ["+15551234567"],
"status": "READY"
}
]
}然后执行激活:
bash
undefinedAuth: same Bearer token header as above
身份验证:使用与上述相同的Bearer令牌请求头
curl -X POST "https://porting.api.sinch.com/v1/projects/$PROJECT_ID/orders/portIns/12345/activate"
-H "Content-Type: application/json"
-H "Authorization: Bearer $ACCESS_TOKEN"
-d '{ "groupIds": ["grp-001"] }'
-H "Content-Type: application/json"
-H "Authorization: Bearer $ACCESS_TOKEN"
-d '{ "groupIds": ["grp-001"] }'
undefinedcurl -X POST "https://porting.api.sinch.com/v1/projects/$PROJECT_ID/orders/portIns/12345/activate"
-H "Content-Type: application/json"
-H "Authorization: Bearer $ACCESS_TOKEN"
-d '{ "groupIds": ["grp-001"] }'
-H "Content-Type: application/json"
-H "Authorization: Bearer $ACCESS_TOKEN"
-d '{ "groupIds": ["grp-001"] }'
undefinedKey Concepts
核心概念
- Port-In Order — A request to transfer one or more phone numbers from another carrier to Sinch. Each order has a numeric and tracks the overall lifecycle.
id - Order Status — Lifecycle of a port-in order: (can update/cancel) →
PENDING(locked, awaiting port date) →CONFIRMED(numbers active). Also:COMPLETED→PENDING_CANCELATION.CANCELED - Phone Number Status — Per-number status within an order: →
PENDING→CONFIRMED. Also:ACTIVATED(seeREJECTED),rejectReason,CANCELED(seeEXCLUDED).exclusionReason - FOC (Firm Order Confirmation) — The confirmed port date set by the losing carrier. Returned as on each phone number once confirmed. On-demand activation requires FOC date to be today or earlier.
focDate - End User — The person or company that currently owns the number. Required fields: ,
name,streetNum,streetName,city,state. Must match the losing carrier's records exactly.zipCode - Port-Out Info — Credentials from the losing carrier. Usually only is needed. May also include
existingPortOutPin,accountNum,accountPhoneNumber,authorizingName.authorizingDate - LOA (Letter of Authorization) — A document authorizing the port. Upload via .
POST /orders/portIns/{orderId}/documents - On-Demand Activation — When , numbers are not auto-activated on the port date. Instead, call
onDemandActivation: trueafter FOC date is reached and numbers are routing on Sinch network.POST /orders/portIns/{orderId}/activate - Voice Configuration — Optional per-number config for voice routing. Discriminated on :
type(programmable voice, requiresRTC),appId(elastic SIP trunking, requiresEST),trunkId(requiresFAX).serviceId - Messaging Configuration — Optional per-number config for messaging features. Supports (Application-to-Person Long Code) and
A2PLCfeature types. Configured alongside voice options on each phone number in the order.SMSMMS - E911 — Optional per-number emergency location data. Submitted as part of the phone number entry in a port-in order for numbers that require E911 service.
- Directory Listing — Optional per-number directory listing information (e.g., name and address for directory assistance). Provided as part of the phone number entry in a port-in order.
- Desired Port Schedule — Required. Contains (ISO date, required),
desiredPortDate(defaults to project config ordesiredPortTime),09:00:00(one of:desiredPortTimeZone,US/Eastern,US/Central,US/Mountain).US/Pacific - Configuration — Project-level defaults for porting: default contact info, webhook URL, default port time and timezone. Set via , updated via
POST /configuration.PUT /configuration
- Port-In Order — 用于将一个或多个电话号码从其他运营商转移至Sinch的请求。每个订单都有一个数字,并跟踪整个生命周期。
id - Order Status — 携号转入订单的生命周期:(可更新/取消)→
PENDING(锁定,等待携转日期)→CONFIRMED(号码已激活)。其他状态包括:COMPLETED→PENDING_CANCELATION。CANCELED - Phone Number Status — 订单内单个号码的状态:→
PENDING→CONFIRMED。其他状态包括:ACTIVATED(查看REJECTED)、rejectReason、CANCELED(查看EXCLUDED)。exclusionReason - FOC (Firm Order Confirmation) — 原运营商确认的携转日期。一旦确认,会以字段返回至每个号码。按需激活要求FOC日期为当天或更早。
focDate - End User — 当前拥有该号码的个人或公司。必填字段:、
name、streetNum、streetName、city、state。信息必须与原运营商记录完全匹配。zipCode - Port-Out Info — 原运营商提供的凭证。通常仅需。也可能包含
existingPortOutPin、accountNum、accountPhoneNumber、authorizingName。authorizingDate - LOA (Letter of Authorization) — 授权携转的文档。通过接口上传。
POST /orders/portIns/{orderId}/documents - On-Demand Activation — 当时,号码不会在携转日期自动激活。需在FOC日期到达且号码已在Sinch网络路由后,调用
onDemandActivation: true接口进行激活。POST /orders/portIns/{orderId}/activate - Voice Configuration — 可选的单号码语音路由配置。通过字段区分类型:
type(可编程语音,需RTC)、appId(弹性SIP中继,需EST)、trunkId(需FAX)。serviceId - Messaging Configuration — 可选的单号码消息功能配置。支持(应用到个人长码)和
A2PLC功能类型。与语音选项一起配置在订单中的每个号码上。SMSMMS - E911 — 可选的单号码紧急位置数据。对于需要E911服务的号码,需作为携号转入订单中号码条目的一部分提交。
- Directory Listing — 可选的单号码目录列表信息(例如,用于目录查询的姓名和地址)。作为携号转入订单中号码条目的一部分提供。
- Desired Port Schedule — 必填字段。包含(ISO格式日期,必填)、
desiredPortDate(默认使用项目配置或desiredPortTime)、09:00:00(可选值:desiredPortTimeZone、US/Eastern、US/Central、US/Mountain)。US/Pacific - Configuration — 携号转的项目级默认设置:默认联系信息、Webhook URL、默认携转时间及时区。通过设置,
POST /configuration更新。PUT /configuration
Common Patterns
常见操作模式
-
Check portability —with
POST /portabilityChecksarray. Always do this before creating an order; non-portable numbers cause order failure.phoneNumbers -
Create port-in order —with
POST /orders/portIns,desiredPortSchedule(each withphoneNumbersandendUser). Returns orderportOutInfoand initialidstatus.PENDING -
List and filter orders —with query params:
GET /orders/portIns,orderStatus,phoneNumber,customerOrderReference/createdDateStart,createdDateEnd/focStartDate,focEndDate(default 100, max 1000),pageSize.page -
Get order details —returns full order with phone numbers, notes, and documents.
GET /orders/portIns/{orderId} -
Get phone number groups —returns phone numbers grouped by their status or activation group within the order. Porting is processed by groups.
GET /orders/portIns/phoneGroups/{orderId} -
Update a pending order —— sends the full object (not a patch). Only works on
PUT /orders/portIns/{orderId}orders.PENDING -
Cancel a pending order —— only works on
DELETE /orders/portIns/{orderId}orders.PENDING -
Add note to order —— use to respond to issues flagged by Sinch during processing.
POST /orders/portIns/{orderId}/notes -
Upload document (LOA) —— attach authorization documents.
POST /orders/portIns/{orderId}/documents -
Get document details —— retrieve metadata or content for a previously uploaded document.
GET /orders/portIns/{orderId}/documents/{documentId} -
On-demand activation — Firstto see which number groups are ready, then
GET /orders/portIns/{orderId}/availableActivationsto activate them. FOC date must be today or earlier and numbers must be routing on Sinch network.POST /orders/portIns/{orderId}/activate -
Configure defaults —to create,
POST /configurationto update,PUT /configurationto read. Sets default contact, webhook URL, port time, and timezone.GET /configuration
-
检查可携性 — 调用接口并传入
POST /portabilityChecks数组。创建订单前务必执行此操作;不可携转的号码会导致订单失败。phoneNumbers -
创建携号转入订单 — 调用接口并传入
POST /orders/portIns、desiredPortSchedule(每个号码需包含phoneNumbers和endUser)。返回订单portOutInfo和初始id状态。PENDING -
列出并筛选订单 — 调用接口并传入查询参数:
GET /orders/portIns、orderStatus、phoneNumber、customerOrderReference/createdDateStart、createdDateEnd/focStartDate、focEndDate(默认100,最大1000)、pageSize。page -
获取订单详情 — 调用接口返回完整订单信息,包括号码、备注和文档。
GET /orders/portIns/{orderId} -
获取号码组 — 调用接口返回订单内按状态或激活组分组的号码。携号转操作按组处理。
GET /orders/portIns/phoneGroups/{orderId} -
更新待处理订单 — 调用接口——需发送完整对象(而非增量更新)。仅对
PUT /orders/portIns/{orderId}状态的订单生效。PENDING -
取消待处理订单 — 调用接口——仅对
DELETE /orders/portIns/{orderId}状态的订单生效。PENDING -
添加订单备注 — 调用接口——用于回复Sinch在处理过程中标记的问题。
POST /orders/portIns/{orderId}/notes -
上传文档(LOA) — 调用接口——附加授权文档。
POST /orders/portIns/{orderId}/documents -
获取文档详情 — 调用接口——检索已上传文档的元数据或内容。
GET /orders/portIns/{orderId}/documents/{documentId} -
按需激活 — 先调用接口查看哪些号码组已准备就绪,再调用
GET /orders/portIns/{orderId}/availableActivations接口激活它们。FOC日期必须为当天或更早,且号码已在Sinch网络路由。POST /orders/portIns/{orderId}/activate -
配置默认设置 — 调用接口创建,
POST /configuration接口更新,PUT /configuration接口读取。设置默认联系人、Webhook URL、携转时间及时区。GET /configuration
Gotchas and Best Practices
注意事项与最佳实践
- Always check portability first — before creating an order. Orders with non-portable numbers will fail.
POST /portabilityChecks - Phone numbers must be E.164 format — All phone numbers in requests must be in E.164 format (e.g., ). Numbers not in this format will be rejected.
+15551234567 - max 100 characters — Longer values will be rejected at validation.
customerOrderReference - North America only — The Porting API currently supports US and CA numbers only (is
countryCodeorUS).CA - Max 500 numbers per order — For orders with more than 500 numbers, contact Sinch support.
- Update is a full PUT, not PATCH — requires the complete order object. Omitting fields will clear them.
PUT /orders/portIns/{orderId} - Only PENDING orders can be updated or canceled — Once , orders cannot be modified. Cancel creates
CONFIRMEDstate during which the same numbers cannot be resubmitted.PENDING_CANCELATION - End user info must match the losing carrier's records — Mismatched name, address, or account details cause rejections. defaults to
typeOfService(Business); set toBfor residential.R - Port-out PIN is usually sufficient — Most carriers only require in
existingPortOutPin. Only provideportOutInfo,accountNum,accountPhoneNumberif the carrier requires them.authorizingName - cannot be in the future — Must be today or earlier.
authorizingDate - Default port time is 09:00 US/Eastern — If you don't set and
desiredPortTimeon the order and haven't configured project defaults, the system usesdesiredPortTimeZone.09:00:00 US/Eastern - Time zones are US-only enum values — Only ,
US/Eastern,US/Central,US/Mountainare accepted. No generic timezone strings.US/Pacific - 10DLC campaign required after port completes — For US 10DLC numbers, you must associate the number with an approved 10DLC campaign before sending SMS/MMS. This can only be done after the port completes.
- Webhooks for real-time updates — Configure a webhook URL via or the dashboard. Use webhooks instead of polling
POST /configurationfor status updates.GET /orders/portIns/{orderId} - is a discriminated union — Must include
voiceConfigurationfield:type(withRTC),appId(withEST), ortrunkId(withFAX).serviceId - No SDK support — The Node.js SDK does not have dedicated porting methods. Use direct REST calls.
@sinch/sdk-core - required for Canadian numbers — An additional field needed when porting CA numbers.
resellerName
- 务必先检查可携性 — 创建订单前调用接口。包含不可携转号码的订单会失败。
POST /portabilityChecks - 电话号码必须为E.164格式 — 请求中的所有电话号码必须为E.164格式(例如)。非该格式的号码会被拒绝。
+15551234567 - 最大长度为100字符 — 超过长度的值会在验证阶段被拒绝。
customerOrderReference - 仅支持北美地区 — Porting API目前仅支持美国和加拿大号码(为
countryCode或US)。CA - 每个订单最多500个号码 — 若订单包含超过500个号码,请联系Sinch支持团队。
- 更新为完整PUT请求,而非PATCH — 调用接口需传入完整订单对象。省略字段会清除对应设置。
PUT /orders/portIns/{orderId} - 仅待处理订单可更新或取消 — 订单进入状态后无法修改。取消操作会创建
CONFIRMED状态,在此期间相同号码无法重新提交。PENDING_CANCELATION - 终端用户信息必须与原运营商记录匹配 — 姓名、地址或账户信息不匹配会导致订单被拒绝。默认值为
typeOfService(企业);个人用户请设置为B。R - 通常仅需携出PIN码 — 大多数运营商仅要求在中提供
portOutInfo。仅当运营商要求时才提供existingPortOutPin、accountNum、accountPhoneNumber。authorizingName - 不能为未来日期 — 必须为当天或更早。
authorizingDate - 默认携转时间为美国东部时间09:00 — 若未在订单中设置和
desiredPortTime,且未配置项目默认值,系统将使用desiredPortTimeZone。09:00:00 US/Eastern - 时区仅支持美国枚举值 — 仅接受、
US/Eastern、US/Central、US/Mountain。不支持通用时区字符串。US/Pacific - 携转完成后需配置10DLC活动 — 对于美国10DLC号码,必须在携转完成后将号码与已批准的10DLC活动关联,才能发送SMS/MMS。
- 使用Webhook获取实时更新 — 通过接口或控制台配置Webhook URL。使用Webhook而非轮询
POST /configuration接口获取状态更新。GET /orders/portIns/{orderId} - 为区分联合类型 — 必须包含
voiceConfiguration字段:type(需RTC)、appId(需EST)或trunkId(需FAX)。serviceId - 无SDK支持 — Node.js SDK没有专门的携号转方法。请使用直接REST调用。
@sinch/sdk-core - 加拿大号码需字段 — 携转加拿大号码时需要额外提供此字段。
resellerName