Skip to content
Numbers/
/
/
Lookup number requirement...

Numbers | Sinch (1.0.3)

Overview

The Numbers API enables you to search for, view, and activate numbers. It's considered a precursor to other APIs in the Sinch product family. The numbers API can be used in tandem with any of our APIs that perform messaging or calling. Once you have activated your numbers, you can then use the various other APIs, such as SMS or Voice, to assign and use those numbers.

Numbers REST formats and conventions

Let's take a brief look at some of the formats used in the REST API.

JSON

JSON (application/json) is the content type of both requests and responses if not otherwise specified.

Requests with invalid JSON will be rejected.

Null values

Null values can be omitted in requests and will be omitted in responses. In some cases, explicitly setting null will overwrite a previously set value with null.

Phone numbers

Only phone numbers in E.164 standard format are accepted by the API.

Examples:

  • US phone number: +13059394139
  • UK phone number: +447478727259
  • SE phone number: +46113232516

Status codes

A summary of status codes can be found on the HTTP status codes page.

IP addresses for callbacks

To successfully use callbacks with Numbers, add the following IP addresses to your allowlist:

  • 54.76.19.159
  • 54.78.194.39
  • 54.155.83.128

New features

New features might result in additional request and response parameters. New request parameters will either have a default value or be considered optional to retain backwards compatibility. It's highly recommended to ignore any unexpected parameters when reading JSON in API responses and in callback handlers.

Download OpenAPI description
numbers.json
numbers.yaml
Overview
URL
https://www.sinch.com
Support
Support@sinch.com
License
MIT
Languages
Servers
Global API
https://numbers.api.sinch.com

Available Numbers

You can use the Available Number API to search for available numbers or activate an available number.

Operations

Number Order

You can use the Number Order API to search for available numbers or activate an available number after providing KYC info.

Steps for buying a number via an order and providing the required KYC information:

  1. "Lookup number requirements" endpoint: look up country KYC requirements to establish which fields / information needs to be provided as part of buying the phone number. Also reveals if any attachment files need to be provided.
  2. "Search for available phone numbers" endpoint: search numbers you may want to buy.
  3. "Create a number order" endpoint: create the Number Order for a specific phone number or for a set of criteria (max 1 number per order supported now), which reserved the number for 48h, giving plenty of time to call the other endpoint to submit the fields required as revealed by the API at 1. and also to hit the final Submit endpoint.
  4. "Update number order registration" endpoint: update the order Registration (container for the actual KYC required fields / information revealed at step #1). This is validated on the spot for required / optional fields, fields lengths etc. (also revealed at step #1).
  5. "Upload an attachment for a number order" endpoint: upload file attachments - only if mandatory as per requirements revealed by step #1. AttachmentId necessary for the URL will be returned at step #1.
  6. "Submit number order" endpoint: submit the order - final step after creating the order and providing registration info and (if required) attachments

You can follow a detailed tutorial outlining the entire ordering process here.

Operations

Lookup number requirements

Request

Returns required KYC fields info based on number type & country legislation.

You can follow a detailed tutorial outlining the entire ordering process here.

Security
Basic or OAuth2.0
Path
projectIdstringrequired

Found on your Sinch Customer Dashboard. Settings > Projects.

Example: YOUR_projectId
Bodyapplication/jsonrequired
regionCodestring(Region Code)

ISO 3166-1 alpha-2 country code of the phone number. Example: US, GB or SE.

Example: "US"
numberTypestring(Type)

The number type.

Default "MOBILE"
Enum ValueDescription
MOBILE

Numbers that belong to a specific range.

LOCAL

Numbers that are assigned to a specific geographic region.

TOLL_FREE

Numbers that are free of charge for the calling party but billed for all arriving calls.

curl -i -X POST \
  -u <username>:<password> \
  https://numbers.api.sinch.com/v1/projects/YOUR_projectId/numberOrders:lookupNumberRequirements \
  -H 'Content-Type: application/json' \
  -d '{
    "regionCode": "AU",
    "numberType": "MOBILE"
  }'

Responses

OK

Bodyapplication/json
fieldsobject

Free-form JSON object of requirements.

attachmentsArray of objects(RequiredAttachment)

List of attachments necessary to be uploaded as part of the KYC process

Response
application/json
{
  "fields": {
    "schema": "/schema/policySchema-v1.json",
    "rules": [ … ],
    "attachments": []
  }
}

Create a number order

Request

Create a number order for a specific number or a set of criteria (quantity, pattern etc.) - reserves the provider numbers for 48h and creates entities for collecting KYC info.

You can follow a detailed tutorial outlining the entire ordering process here.

Security
Basic or OAuth2.0
Path
projectIdstringrequired

Found on your Sinch Customer Dashboard. Settings > Projects.

Example: YOUR_projectId
Bodyapplication/jsonrequired
One of:

Create a number order

numberOrderOptionobject(CreateNumberOrderOption)required
numberOrderOption.​phoneNumbersArray of strings
Example: ["+12311234567"]
regionCodestring(Region Code)

ISO 3166-1 alpha-2 country code of the phone number. Example: US, GB or SE.

Example: "US"
numberTypestring(Type)

The number type.

Default "MOBILE"
Enum ValueDescription
MOBILE

Numbers that belong to a specific range.

LOCAL

Numbers that are assigned to a specific geographic region.

TOLL_FREE

Numbers that are free of charge for the calling party but billed for all arriving calls.

smsConfigurationobject(Base SMS Configuration)

SMS Configuration for KYC numbers, containing the servicePlanId and campaignId.

voiceConfigurationobject(OrderVoiceConfiguration)
callbackUrlstring(uri)
curl -i -X POST \
  -u <username>:<password> \
  https://numbers.api.sinch.com/v1/projects/YOUR_projectId/numberOrders:createNumberOrder \
  -H 'Content-Type: application/json' \
  -d '{
    "regionCode": "AU",
    "numberType": "MOBILE",
    "smsConfiguration": {
      "servicePlanId": "1dez6a8300774283a4256aa756a11111"
    },
    "callbackUrl": "https://www.your-callback-server.com/callback",
    "numberOrderOption": {
      "phoneNumbers": [
        "+61411111112"
      ]
    }
  }'

Responses

OK

Bodyapplication/json
projectIdstring
idNumberOrderstring
regionCodestring(Region Code)

ISO 3166-1 alpha-2 country code of the phone number. Example: US, GB or SE.

Example: "US"
statestring(Number Order State)

The state of the number order

Enum ValueDescription
NUMBER_ORDER_STATE_UNSPECIFIED

State not specified.

CREATED

Created state.

EXPIRED

Expired state.

IN_REVIEW

Order in review.

BLOCKED

Order blocked.

REJECTED

Order rejected.

COMPLETED

Order completed.

numberTypestring(Type)

The number type.

Default "MOBILE"
Enum ValueDescription
MOBILE

Numbers that belong to a specific range.

LOCAL

Numbers that are assigned to a specific geographic region.

TOLL_FREE

Numbers that are free of charge for the calling party but billed for all arriving calls.

orderNumbersArray of objects(OrderNumber)
smsConfigurationobject(Base SMS Configuration)

SMS Configuration for KYC numbers, containing the servicePlanId and campaignId.

voiceConfigurationobject(OrderVoiceConfiguration)
expireTimestring or null(date-time)
Example: "2025-11-23T08:54:58.115Z"
createTimestring(date-time)
updateTimestring(date-time)
Response
application/json
{
  "projectId": "10d64985-0bfb-43d3-a2b9-bc5fa6a4752c",
  "idNumberOrder": "03kjzencnckxrn216rr1zzzzzz",
  "regionCode": "AU",
  "state": "CREATED",
  "numberType": "MOBILE",
  "orderNumbers": [
    { … }
  ],
  "smsConfiguration": {
    "servicePlanId": "1dez6a8300774283a4256aa756a11111"
  },
  "expireTime": "2026-03-07T16:53:00.204187Z",
  "createTime": "2026-03-05T16:53:00Z",
  "updateTime": "2026-03-05T16:53:00Z"
}

Get a number order

Request

Returns the number order alongside all reserved numbers.

You can follow a detailed tutorial outlining the entire ordering process here.

Security
Basic or OAuth2.0
Path
projectIdstringrequired

Found on your Sinch Customer Dashboard. Settings > Projects.

Example: YOUR_projectId
numberOrderIdstringrequired

The ID of the number order created by the REST API user.

curl -i -X GET \
  -u <username>:<password> \
  'https://numbers.api.sinch.com/v1/projects/YOUR_projectId/numberOrders/{numberOrderId}'

Responses

OK

Bodyapplication/json
projectIdstring
idNumberOrderstring
regionCodestring(Region Code)

ISO 3166-1 alpha-2 country code of the phone number. Example: US, GB or SE.

Example: "US"
statestring(Number Order State)

The state of the number order

Enum ValueDescription
NUMBER_ORDER_STATE_UNSPECIFIED

State not specified.

CREATED

Created state.

EXPIRED

Expired state.

IN_REVIEW

Order in review.

BLOCKED

Order blocked.

REJECTED

Order rejected.

COMPLETED

Order completed.

numberTypestring(Type)

The number type.

Default "MOBILE"
Enum ValueDescription
MOBILE

Numbers that belong to a specific range.

LOCAL

Numbers that are assigned to a specific geographic region.

TOLL_FREE

Numbers that are free of charge for the calling party but billed for all arriving calls.

orderNumbersArray of objects(OrderNumber)
smsConfigurationobject(Base SMS Configuration)

SMS Configuration for KYC numbers, containing the servicePlanId and campaignId.

voiceConfigurationobject(OrderVoiceConfiguration)
expireTimestring or null(date-time)
Example: "2025-11-23T08:54:58.115Z"
createTimestring(date-time)
updateTimestring(date-time)
Response
application/json
{
  "projectId": "10d64985-0bfb-43d3-a2b9-bc5fa6a4752c",
  "idNumberOrder": "03kjzencnckxrn216rr1zzzzzz",
  "regionCode": "AU",
  "state": "CREATED",
  "numberType": "MOBILE",
  "orderNumbers": [
    { … }
  ],
  "smsConfiguration": {
    "servicePlanId": "1dez6a8300774283a4256aa756a11111"
  },
  "expireTime": "2026-03-07T16:53:00.204187Z",
  "createTime": "2026-03-05T16:53:00Z",
  "updateTime": "2026-03-05T16:53:00Z"
}

Update number order registration

Request

Updates the registration (vehicle for KYC info) for a specific number order. Validated against the country requirements revealed by the "Lookup number requirements" endpoints.

You can follow a detailed tutorial outlining the entire ordering process here.

Security
Basic or OAuth2.0
Path
projectIdstringrequired

Found on your Sinch Customer Dashboard. Settings > Projects.

Example: YOUR_projectId
numberOrderIdstringrequired

The ID of the number order created by the REST API user.

Bodyapplication/jsonrequired
dataobject

Free-form JSON object representing registration data.

curl -i -X PUT \
  -u <username>:<password> \
  'https://numbers.api.sinch.com/v1/projects/YOUR_projectId/numberOrders/{numberOrderId}/registration' \
  -H 'Content-Type: application/json' \
  -d '{
    "requestDetails": {
      "data": [
        [
          {
            "senderId": "+61XXXXXXXXX",
            "purposeOfTheTraffic": "One Time Password",
            "intendedUseOfMobileNumbers": "Transactional",
            "iConfirmThatMyBusinessHasAValidUseCaseForThisLn": true
          }
        ],
        {
          "endBusinessName": "ExampleExample",
          "endBusinessAddress": "ExampleExample",
          "endBusinessAddress2": "ExampleExample",
          "city": "Victoria",
          "state": "VIC",
          "country": "AU",
          "postalCode": "3000"
        },
        {
          "firstName": "Example",
          "lastName": "Example",
          "phoneNumber": "+61XXXXXXXXX"
        }
      ]
    }
  }'

Responses

OK

Bodyapplication/json
dataobject

Free-form JSON object representing registration data.

attachmentsArray of objects(Attachment)
Response
application/json
{
  "requestDetails": {
    "data": [ … ]
  }
}

Get number order registration

Request

Retrieves the Registration submitted for a number order via the "Update number order registration" endpoint.

You can follow a detailed tutorial outlining the entire ordering process here.

Security
Basic or OAuth2.0
Path
projectIdstringrequired

Found on your Sinch Customer Dashboard. Settings > Projects.

Example: YOUR_projectId
numberOrderIdstringrequired

The ID of the number order created by the REST API user.

curl -i -X GET \
  -u <username>:<password> \
  'https://numbers.api.sinch.com/v1/projects/YOUR_projectId/numberOrders/{numberOrderId}/registration'

Responses

OK

Bodyapplication/json
dataobject

Free-form JSON object representing registration data.

attachmentsArray of objects(Attachment)
Response
application/json
{
  "requestDetails": {
    "data": [ … ]
  }
}

Upload an attachment for a number order

Request

Upload file attachments to a number order registration. Mandatory only if revealed in the requirements returned by the "Lookup number requirements" endpoint.

The "attachmentId" URL parameter is the one returned by the "Lookup number requirements" endpoint.

You can follow a detailed tutorial outlining the entire ordering process here.

Security
Basic or OAuth2.0
Path
projectIdstringrequired

Found on your Sinch Customer Dashboard. Settings > Projects.

Example: YOUR_projectId
numberOrderIdstringrequired

The ID of the number order created by the REST API user.

attachmentIdstringrequired

attachment IDs are returned by the "Lookup number requirements" endpoint

Example: d1c7ccbf-919d-462f-8587-dec95a1b11zz
Bodymultipart/form-datarequired

File attachment upload request body with Content-Type = multipart/form-data

filestring(binary)required

File attachment to upload

documentTypestring

Optional document type associated with the uploaded attachment

curl -i -X POST \
  -u <username>:<password> \
  'https://numbers.api.sinch.com/v1/projects/YOUR_projectId/numberOrders/{numberOrderId}/attachments/d1c7ccbf-919d-462f-8587-dec95a1b11zz' \
  -H 'Content-Type: multipart/form-data' \
  -F file=string \
  -F documentType=string

Responses

Document uploaded successfully

Response
No content

Submit number order

Request

Submits the order for review, assuming the KYC info and attachments were submitted using their dedicated endpoints.

You can follow a detailed tutorial outlining the entire ordering process here.

Security
Basic or OAuth2.0
Path
projectIdstringrequired

Found on your Sinch Customer Dashboard. Settings > Projects.

Example: YOUR_projectId
numberOrderIdstringrequired

The ID of the number order created by the REST API user.

curl -i -X POST \
  -u <username>:<password> \
  'https://numbers.api.sinch.com/v1/projects/YOUR_projectId/numberOrders/{numberOrderId}/submit'

Responses

OK

Bodyapplication/json
projectIdstring
idNumberOrderstring
regionCodestring(Region Code)

ISO 3166-1 alpha-2 country code of the phone number. Example: US, GB or SE.

Example: "US"
statestring(Number Order State)

The state of the number order

Enum ValueDescription
NUMBER_ORDER_STATE_UNSPECIFIED

State not specified.

CREATED

Created state.

EXPIRED

Expired state.

IN_REVIEW

Order in review.

BLOCKED

Order blocked.

REJECTED

Order rejected.

COMPLETED

Order completed.

numberTypestring(Type)

The number type.

Default "MOBILE"
Enum ValueDescription
MOBILE

Numbers that belong to a specific range.

LOCAL

Numbers that are assigned to a specific geographic region.

TOLL_FREE

Numbers that are free of charge for the calling party but billed for all arriving calls.

orderNumbersArray of objects(OrderNumber)
smsConfigurationobject(Base SMS Configuration)

SMS Configuration for KYC numbers, containing the servicePlanId and campaignId.

voiceConfigurationobject(OrderVoiceConfiguration)
expireTimestring or null(date-time)
Example: "2025-11-23T08:54:58.115Z"
createTimestring(date-time)
updateTimestring(date-time)
Response
application/json
{
  "projectId": "10d64985-0bfb-43d3-a2b9-bc5fa6a4752c",
  "idNumberOrder": "03kjzencnckxrn216rr1zzzzzz",
  "regionCode": "AU",
  "state": "CREATED",
  "numberType": "MOBILE",
  "orderNumbers": [
    { … }
  ],
  "smsConfiguration": {
    "servicePlanId": "1dez6a8300774283a4256aa756a11111"
  },
  "expireTime": "2026-03-07T16:53:00.204187Z",
  "createTime": "2026-03-05T16:53:00Z",
  "updateTime": "2026-03-05T16:53:00Z"
}

Active Numbers

You can use the Active Number API to manage numbers you own. Release numbers from projects or list all numbers assigned to a project.

Operations

Available Regions

You can use the Available Regions API to list all of the regions that have numbers assigned to a project.

Operations

Numbers Callbacks

You can set up callback URLs to receive event notifications when your numbers are updated.

When delivering events the order is not guaranteed (for example, a failed event scheduled for retry will not block other events that were queued).

The client's callback handler must implement the state machine that can decide what to do with unexpected events, for example, "old" events or invalid state transitions. In these cases the handler could use the API to GET the latest state for the resource.

The callback handler is expected to "ingest" the event and respond with 200 OK. The domain-specific business logic and processes should be executed outside of the callback request, as internal asynchronous jobs.

To use callbacks, add the following IP addresses to your allowlist:

  • 54.76.19.159
  • 54.78.194.39
  • 54.155.83.128
Operations
Webhooks