sinch-numbers-api

Original：🇺🇸 English

Translated

1 scripts

Search, rent, manage, and release phone numbers with the Sinch Numbers API. Use when listing active numbers, searching available numbers, renting or releasing numbers, updating number configuration (SMS/voice/callback), managing emergency addresses, or checking available regions.

3installs

Sourcesinch/skills

Added on2026-03-27

NPX Install

npx skill4agent add sinch/skills sinch-numbers-api

SKILL.md Content

View Translation Comparison →

Sinch Numbers API

The Numbers API lets you search, activate, manage, and release phone numbers — the prerequisite for SMS, Voice, and Conversation APIs.

Instructions

Step 1: Choose approach

SDK project? Default to SDK if
```
@sinch/sdk-core
```
(Node),
```
sinch
```
(Python), or
```
com.sinch.sdk
```
(Java) is present.
Direct HTTP? Use curl/fetch with Basic auth.

For SDK code, read the correct reference before generating any code:

Language	Reference	SDK docs
TypeScript/Node.js	references/typescript.md	Syntax reference
Python	references/python.md	Syntax reference
Java	references/java.md	Syntax reference

For direct HTTP calls, see Numbers API Reference.

Step 2: Authenticate

See sinch-authentication for full setup. Use Basic auth (

-u KEY_ID:KEY_SECRET

) for quick starts, OAuth2 for production.

Step 3: Verify connectivity

bash

curl -X GET "https://numbers.api.sinch.com/v1/projects/{PROJECT_ID}/activeNumbers?regionCode=US&type=LOCAL&pageSize=10" \
  -u {KEY_ID}:{KEY_SECRET}

A 200 response confirms credentials and project access.

Workflows

Search and rent a number

```
GET /availableRegions
```
— discover valid
```
regionCode
```
values

GET /availableNumbers?regionCode={code}&type={type}

— search (both params required)

Pick a number →

POST /availableNumbers/{phoneNumber}:rent

with config body

```
GET /activeNumbers/{phoneNumber}
```
— confirm activation

Use

POST /availableNumbers:rentAny

to skip step 3 (US LOCAL numbers only).

Safe retries for billable operations

Before retrying any potentially billable action (for example

:rent

,

:rentAny

, or

:release

) after an incomplete/uncertain response:

Check current state first using a read endpoint (
```
GET /activeNumbers/{phoneNumber}
```
or
```
GET /activeNumbers
```
with filters)
Retry only if the verification shows the prior action did not succeed
If state is ambiguous, prefer listing active numbers and matching on
```
phoneNumber
```
before issuing another billable request

Update number configuration

```
GET /activeNumbers/{phoneNumber}
```
— check current config

PATCH /activeNumbers/{phoneNumber}

— set

displayName

,

smsConfiguration

, or

voiceConfiguration

To unlink, send empty string
```
""
```
in
```
servicePlanId
```
or
```
campaignId
```

Release a number

POST /activeNumbers/{phoneNumber}:release

Fetch all numbers to JSON

Run

node scripts/get_numbers.cjs --output numbers.json

(uses

SINCH_PROJECT_ID

,

SINCH_KEY_ID

,

SINCH_KEY_SECRET

env vars). Supports

--region

and

--type

filters.

Emergency addresses

Use the emergency address endpoints on active numbers:

GET

,

provision

,

deprovision

,

validate

. See API reference.

Number orders (KYC-regulated regions)

Use the

numberOrders

endpoints:

lookupNumberRequirements

→

createNumberOrder

→ upload registration/attachments →

submit

. See API reference.

Imported numbers

A separate API at

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

handles importing non-Sinch numbers (DCA) and hosting orders. See API reference.

Gotchas

Param names differ between endpoints:
```
GET /activeNumbers
```
uses
```
capability
```
(singular) and
```
pageSize
```
.
```
GET /availableNumbers
```
uses
```
capabilities
```
(plural) and
```
size
```
(single page, no pagination).
type
defaults to
MOBILE
— omitting it returns only MOBILE numbers, not all types.
Always set
pageSize
explicitly on
```
GET /activeNumbers
```
— no documented default.
rentAny
is US LOCAL only — use
```
:rent
```
for other types/regions.
Do not blindly retry billable actions — if output is incomplete, verify state via
```
GET /activeNumbers/{phoneNumber}
```
(or list + filter) before retrying
```
:rent
```
,
```
:rentAny
```
, or
```
:release
```
.
Never pass both config objects unnecessarily — sending empty
```
voiceConfiguration
```
when you only need SMS will error.
Unlink before relinking — a number must be detached from its current service/campaign before attaching to a new one.
campaignId
is US-only — required for 10DLC, irrelevant elsewhere.

scheduledProvisioning
/
scheduledVoiceProvisioning
are objects (with

status

,

lastUpdatedTime

,

errorCodes

), not strings. Status values:

PROVISIONING_STATUS_UNSPECIFIED

,

WAITING

,

IN_PROGRESS

,

FAILED

.

voiceConfiguration
is a discriminated union on

type

:

RTC

→

appId

,

EST

→

trunkId

,

FAX

→

serviceId

.

Callback config (
```
PATCH /callbackConfiguration
```
) sets only
```
hmacSecret
```
for HMAC-SHA1 signature verification — it does not set a callback URL.
Callback IP allowlist:
```
54.76.19.159
```
,
```
54.78.194.39
```
,
```
54.155.83.128
```
.