Sinch Imported Numbers & Hosting Orders

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.

Agent Instructions

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.

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)

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.

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).

First API Call — Import a Number

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

Workflows

Workflow A: Import Single Number

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

Workflow B: Bulk Import via Hosting Order

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

Workflow C: Qualify Numbers

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

Workflow D: Text-Enable Numbers

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)

Workflow E: Check Hosting Order Status

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

Workflow F: Manage Numbers & Verification

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

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

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

sinch-imported-numbers-hosting-orders

NPX Install

Tags

SKILL.md Content

Sinch Imported Numbers & Hosting Orders

Overview

Agent Instructions

Decision Tree

Critical Rules

Getting Started

Authentication

First API Call — Import a Number

Key Concepts

Workflows

Workflow A: Import Single Number

Workflow B: Bulk Import via Hosting Order

Workflow C: Qualify Numbers

Workflow D: Text-Enable Numbers

Workflow E: Check Hosting Order Status

Workflow F: Manage Numbers & Verification

Callbacks

Gotchas and Best Practices

Links