sinch-porting-api

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Sinch 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:
  1. Approach — SDK or direct API calls (curl/fetch)?
  2. Use case — Portability check, create order, track order, activate numbers?
  3. Activation mode (only for create order) — Automatic (on
    desiredPortDate
    ) or on-demand (
    onDemandActivation: true
    )?
Note: The
@sinch/sdk-core
Node.js SDK does not currently have dedicated porting methods. Use direct HTTP calls for all porting operations.
在生成代码之前,需向用户收集以下信息:
  1. 实现方式——使用SDK还是直接调用API(curl/fetch)?
  2. 使用场景——可携性检查、创建订单、跟踪订单、激活号码?
  3. 激活模式(仅创建订单时需要)——自动激活(在
    desiredPortDate
    日期)还是按需激活(
    onDemandActivation: true
    )?
注意:
@sinch/sdk-core
Node.js SDK目前没有专门的携号转方法。所有携号转操作均需使用直接HTTP调用。

Getting Started

快速开始

Authentication

身份验证

See sinch-authentication for full setup.
完整设置请参考sinch-authentication

Base URL

基础URL

EnvironmentURL
Production
https://porting.api.sinch.com/v1/projects/{PROJECT_ID}
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
生产环境
https://porting.api.sinch.com/v1/projects/{PROJECT_ID}
将凭证存储在环境变量中——切勿在命令或源代码中硬编码令牌、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"
        }
      }
    ]
  }'
existingPortOutPin
— Obtain this PIN from the losing carrier before submitting the order. See Create Port-In Order for full field reference.
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"
        }
      }
    ]
  }'
existingPortOutPin
— 提交订单前需从原运营商获取此PIN码。完整字段参考请查看Create Port-In Order
响应:
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
undefined
bash
undefined

Auth: same Bearer token header as above

身份验证:使用与上述相同的Bearer令牌请求头


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"
    }
  ]
}

响应:

```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
undefined

Auth: same Bearer token header as above

身份验证:使用与上述相同的Bearer令牌请求头


Response:

```json
{
  "activationGroups": [
    {
      "groupId": "grp-001",
      "phoneNumbers": ["+15551234567"],
      "status": "READY"
    }
  ]
}
Then activate:
bash
undefined

响应:

```json
{
  "activationGroups": [
    {
      "groupId": "grp-001",
      "phoneNumbers": ["+15551234567"],
      "status": "READY"
    }
  ]
}
然后执行激活:
bash
undefined

Auth: 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"] }'
undefined
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"] }'
undefined

Key Concepts

核心概念

  • Port-In Order — A request to transfer one or more phone numbers from another carrier to Sinch. Each order has a numeric
    id
    and tracks the overall lifecycle.
  • Order Status — Lifecycle of a port-in order:
    PENDING
    (can update/cancel) →
    CONFIRMED
    (locked, awaiting port date) →
    COMPLETED
    (numbers active). Also:
    PENDING_CANCELATION
    CANCELED
    .
  • Phone Number Status — Per-number status within an order:
    PENDING
    CONFIRMED
    ACTIVATED
    . Also:
    REJECTED
    (see
    rejectReason
    ),
    CANCELED
    ,
    EXCLUDED
    (see
    exclusionReason
    ).
  • FOC (Firm Order Confirmation) — The confirmed port date set by the losing carrier. Returned as
    focDate
    on each phone number once confirmed. On-demand activation requires FOC date to be today or earlier.
  • End User — The person or company that currently owns the number. Required fields:
    name
    ,
    streetNum
    ,
    streetName
    ,
    city
    ,
    state
    ,
    zipCode
    . Must match the losing carrier's records exactly.
  • Port-Out Info — Credentials from the losing carrier. Usually only
    existingPortOutPin
    is needed. May also include
    accountNum
    ,
    accountPhoneNumber
    ,
    authorizingName
    ,
    authorizingDate
    .
  • LOA (Letter of Authorization) — A document authorizing the port. Upload via
    POST /orders/portIns/{orderId}/documents
    .
  • On-Demand Activation — When
    onDemandActivation: true
    , numbers are not auto-activated on the port date. Instead, call
    POST /orders/portIns/{orderId}/activate
    after FOC date is reached and numbers are routing on Sinch network.
  • Voice Configuration — Optional per-number config for voice routing. Discriminated on
    type
    :
    RTC
    (programmable voice, requires
    appId
    ),
    EST
    (elastic SIP trunking, requires
    trunkId
    ),
    FAX
    (requires
    serviceId
    ).
  • Messaging Configuration — Optional per-number config for messaging features. Supports
    A2PLC
    (Application-to-Person Long Code) and
    SMSMMS
    feature types. Configured alongside voice options on each phone number in the order.
  • 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
    desiredPortDate
    (ISO date, required),
    desiredPortTime
    (defaults to project config or
    09:00:00
    ),
    desiredPortTimeZone
    (one of:
    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
    POST /configuration
    , updated via
    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) — 原运营商确认的携转日期。一旦确认,会以
    focDate
    字段返回至每个号码。按需激活要求FOC日期为当天或更早。
  • 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 — 当
    onDemandActivation: true
    时,号码不会在携转日期自动激活。需在FOC日期到达且号码已在Sinch网络路由后,调用
    POST /orders/portIns/{orderId}/activate
    接口进行激活。
  • Voice Configuration — 可选的单号码语音路由配置。通过
    type
    字段区分类型:
    RTC
    (可编程语音,需
    appId
    )、
    EST
    (弹性SIP中继,需
    trunkId
    )、
    FAX
    (需
    serviceId
    )。
  • Messaging Configuration — 可选的单号码消息功能配置。支持
    A2PLC
    (应用到个人长码)和
    SMSMMS
    功能类型。与语音选项一起配置在订单中的每个号码上。
  • E911 — 可选的单号码紧急位置数据。对于需要E911服务的号码,需作为携号转入订单中号码条目的一部分提交。
  • Directory Listing — 可选的单号码目录列表信息(例如,用于目录查询的姓名和地址)。作为携号转入订单中号码条目的一部分提供。
  • Desired Port Schedule — 必填字段。包含
    desiredPortDate
    (ISO格式日期,必填)、
    desiredPortTime
    (默认使用项目配置或
    09:00:00
    )、
    desiredPortTimeZone
    (可选值:
    US/Eastern
    US/Central
    US/Mountain
    US/Pacific
    )。
  • Configuration — 携号转的项目级默认设置:默认联系信息、Webhook URL、默认携转时间及时区。通过
    POST /configuration
    设置,
    PUT /configuration
    更新。

Common Patterns

常见操作模式

  • Check portability
    POST /portabilityChecks
    with
    phoneNumbers
    array. Always do this before creating an order; non-portable numbers cause order failure.
  • Create port-in order
    POST /orders/portIns
    with
    desiredPortSchedule
    ,
    phoneNumbers
    (each with
    endUser
    and
    portOutInfo
    ). Returns order
    id
    and initial
    PENDING
    status.
  • List and filter orders
    GET /orders/portIns
    with query params:
    orderStatus
    ,
    phoneNumber
    ,
    customerOrderReference
    ,
    createdDateStart
    /
    createdDateEnd
    ,
    focStartDate
    /
    focEndDate
    ,
    pageSize
    (default 100, max 1000),
    page
    .
  • Get order details
    GET /orders/portIns/{orderId}
    returns full order with phone numbers, notes, and documents.
  • Get phone number groups
    GET /orders/portIns/phoneGroups/{orderId}
    returns phone numbers grouped by their status or activation group within the order. Porting is processed by groups.
  • Update a pending order
    PUT /orders/portIns/{orderId}
    — sends the full object (not a patch). Only works on
    PENDING
    orders.
  • Cancel a pending order
    DELETE /orders/portIns/{orderId}
    — only works on
    PENDING
    orders.
  • Add note to order
    POST /orders/portIns/{orderId}/notes
    — use to respond to issues flagged by Sinch during processing.
  • Upload document (LOA)
    POST /orders/portIns/{orderId}/documents
    — attach authorization documents.
  • Get document details
    GET /orders/portIns/{orderId}/documents/{documentId}
    — retrieve metadata or content for a previously uploaded document.
  • On-demand activation — First
    GET /orders/portIns/{orderId}/availableActivations
    to see which number groups are ready, then
    POST /orders/portIns/{orderId}/activate
    to activate them. FOC date must be today or earlier and numbers must be routing on Sinch network.
  • Configure defaults
    POST /configuration
    to create,
    PUT /configuration
    to update,
    GET /configuration
    to read. Sets default contact, webhook URL, port time, and timezone.
  • 检查可携性 — 调用
    POST /portabilityChecks
    接口并传入
    phoneNumbers
    数组。创建订单前务必执行此操作;不可携转的号码会导致订单失败。
  • 创建携号转入订单 — 调用
    POST /orders/portIns
    接口并传入
    desiredPortSchedule
    phoneNumbers
    (每个号码需包含
    endUser
    portOutInfo
    )。返回订单
    id
    和初始
    PENDING
    状态。
  • 列出并筛选订单 — 调用
    GET /orders/portIns
    接口并传入查询参数:
    orderStatus
    phoneNumber
    customerOrderReference
    createdDateStart
    /
    createdDateEnd
    focStartDate
    /
    focEndDate
    pageSize
    (默认100,最大1000)、
    page
  • 获取订单详情 — 调用
    GET /orders/portIns/{orderId}
    接口返回完整订单信息,包括号码、备注和文档。
  • 获取号码组 — 调用
    GET /orders/portIns/phoneGroups/{orderId}
    接口返回订单内按状态或激活组分组的号码。携号转操作按组处理。
  • 更新待处理订单 — 调用
    PUT /orders/portIns/{orderId}
    接口——需发送完整对象(而非增量更新)。仅对
    PENDING
    状态的订单生效。
  • 取消待处理订单 — 调用
    DELETE /orders/portIns/{orderId}
    接口——仅对
    PENDING
    状态的订单生效。
  • 添加订单备注 — 调用
    POST /orders/portIns/{orderId}/notes
    接口——用于回复Sinch在处理过程中标记的问题。
  • 上传文档(LOA) — 调用
    POST /orders/portIns/{orderId}/documents
    接口——附加授权文档。
  • 获取文档详情 — 调用
    GET /orders/portIns/{orderId}/documents/{documentId}
    接口——检索已上传文档的元数据或内容。
  • 按需激活 — 先调用
    GET /orders/portIns/{orderId}/availableActivations
    接口查看哪些号码组已准备就绪,再调用
    POST /orders/portIns/{orderId}/activate
    接口激活它们。FOC日期必须为当天或更早,且号码已在Sinch网络路由。
  • 配置默认设置 — 调用
    POST /configuration
    接口创建,
    PUT /configuration
    接口更新,
    GET /configuration
    接口读取。设置默认联系人、Webhook URL、携转时间及时区。

Gotchas and Best Practices

注意事项与最佳实践

  • Always check portability first
    POST /portabilityChecks
    before creating an order. Orders with non-portable numbers will fail.
  • Phone numbers must be E.164 format — All phone numbers in requests must be in E.164 format (e.g.,
    +15551234567
    ). Numbers not in this format will be rejected.
  • customerOrderReference
    max 100 characters
    — Longer values will be rejected at validation.
  • North America only — The Porting API currently supports US and CA numbers only (
    countryCode
    is
    US
    or
    CA
    ).
  • Max 500 numbers per order — For orders with more than 500 numbers, contact Sinch support.
  • Update is a full PUT, not PATCH
    PUT /orders/portIns/{orderId}
    requires the complete order object. Omitting fields will clear them.
  • Only PENDING orders can be updated or canceled — Once
    CONFIRMED
    , orders cannot be modified. Cancel creates
    PENDING_CANCELATION
    state during which the same numbers cannot be resubmitted.
  • End user info must match the losing carrier's records — Mismatched name, address, or account details cause rejections.
    typeOfService
    defaults to
    B
    (Business); set to
    R
    for residential.
  • Port-out PIN is usually sufficient — Most carriers only require
    existingPortOutPin
    in
    portOutInfo
    . Only provide
    accountNum
    ,
    accountPhoneNumber
    ,
    authorizingName
    if the carrier requires them.
  • authorizingDate
    cannot be in the future
    — Must be today or earlier.
  • Default port time is 09:00 US/Eastern — If you don't set
    desiredPortTime
    and
    desiredPortTimeZone
    on the order and haven't configured project defaults, the system uses
    09:00:00 US/Eastern
    .
  • Time zones are US-only enum values — Only
    US/Eastern
    ,
    US/Central
    ,
    US/Mountain
    ,
    US/Pacific
    are accepted. No generic timezone strings.
  • 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
    POST /configuration
    or the dashboard. Use webhooks instead of polling
    GET /orders/portIns/{orderId}
    for status updates.
  • voiceConfiguration
    is a discriminated union
    — Must include
    type
    field:
    RTC
    (with
    appId
    ),
    EST
    (with
    trunkId
    ), or
    FAX
    (with
    serviceId
    ).
  • No SDK support — The
    @sinch/sdk-core
    Node.js SDK does not have dedicated porting methods. Use direct REST calls.
  • resellerName
    required for Canadian numbers
    — An additional field needed when porting CA numbers.
  • 务必先检查可携性 — 创建订单前调用
    POST /portabilityChecks
    接口。包含不可携转号码的订单会失败。
  • 电话号码必须为E.164格式 — 请求中的所有电话号码必须为E.164格式(例如
    +15551234567
    )。非该格式的号码会被拒绝。
  • customerOrderReference
    最大长度为100字符
    — 超过长度的值会在验证阶段被拒绝。
  • 仅支持北美地区 — 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获取实时更新 — 通过
    POST /configuration
    接口或控制台配置Webhook URL。使用Webhook而非轮询
    GET /orders/portIns/{orderId}
    接口获取状态更新。
  • voiceConfiguration
    为区分联合类型
    — 必须包含
    type
    字段:
    RTC
    (需
    appId
    )、
    EST
    (需
    trunkId
    )或
    FAX
    (需
    serviceId
    )。
  • 无SDK支持
    @sinch/sdk-core
    Node.js SDK没有专门的携号转方法。请使用直接REST调用。
  • 加拿大号码需
    resellerName
    字段
    — 携转加拿大号码时需要额外提供此字段。

Links

相关链接