Skip to content
Numbers/
API reference
/
/Available Number

Numbers | Sinch (1.0.3)

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 Number

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

Operations

Activate a new phone number

Request

Activate a phone number to use with SMS products, Voice products, or both.

You'll use smsConfiguration to setup your number for SMS and voiceConfiguration for Voice. To setup for both, add both objects. See the dropdown menu (just under language selection) for code samples.

Note: You cannot add both objects if you only need to configure one object. For example, if you only need to configure smsConfiguration for SMS messaging, do not add the voiceConfiguration object or it will result in an error.

Security
Basic or OAuth2.0
Path
projectIdstringrequired

Found on your Sinch Customer Dashboard. Settings > Projects.

Example: YOUR_projectId
phoneNumberstringrequired

Output only. The phone number in E.164 format with leading +.

Default "YOUR_selected_phoneNumber_from_search"
Example: +12025550134
Bodyapplication/jsonrequired

The request to rent a number.

smsConfigurationobject(SMS Configuration)

The current SMS configuration for this number.

Once the servicePlanId is sent, it enters scheduled provisioning.

The status of scheduled provisioning will show under a scheduledProvisioning object if it's still running. Once processed successfully, the servicePlanId sent will appear directly under the smsConfiguration object.

voiceConfigurationobject(VoiceConfiguration)

The current voice configuration for this number. During scheduled provisioning, the app ID, service ID, or trunk ID value may be empty in a response if it is still processing or if it has failed. The status of scheduled provisioning will show under a scheduledVoiceProvisioning object if it's still running. Once processed successfully, the appId/serviceId/trunkId sent will appear directly under the voiceConfiguration object.

callbackUrlstring

The callback URL to be called for a rented number's provisioning / deprovisioning operations.

curl -i -X POST \
  -u <username>:<password> \
  'https://numbers.api.sinch.com/v1/projects/YOUR_projectId/availableNumbers/+12025550134:rent' \
  -H 'Content-Type: application/json' \
  -d '{
    "smsConfiguration": {
      "servicePlanId": "YOUR_SMS_servicePlanId"
    },
    "voiceConfiguration": {
      "type": "RTC",
      "appId": "YOUR_Voice_appId"
    },
    "callbackUrl": "https://www.your-callback-server.com/callback"
  }'

Responses

A successful response, or an Error.

Bodyapplication/json
phoneNumberstring

The phone number in E.164 format with leading +. Example: +12025550134.

Example: "+12025550134"
projectIdstring

Project ID. Your project ID can be found on your Sinch Customer Dashboard.

Example: "51bc3f40-f266-4ca8-8938-a1ed0ff32b9a"
displayNamestring

User supplied name for the phone number.

regionCodestringread-only

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

Example: "US"
typestring(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.

capabilityArray of strings(Capability)

The capability of the number.

Items Enum ValueDescription
SMS

The SMS product can use the number.

VOICE

The Voice product can use the number.

Example: ["SMS"]
moneyobject(Money)

An object giving details on currency code and the amount charged.

paymentIntervalMonthsinteger(int32)read-only

How often the recurring price is charged in months.

nextChargeDatestring(date-time)read-only

The date of the next charge.

expireAtstring(date-time)read-only

The timestamp when the subscription will expire if an expiration date has been set.

smsConfigurationobject(SMS Configuration)

The current SMS configuration for this number.

Once the servicePlanId is sent, it enters scheduled provisioning.

The status of scheduled provisioning will show under a scheduledProvisioning object if it's still running. Once processed successfully, the servicePlanId sent will appear directly under the smsConfiguration object.

voiceConfigurationobject(VoiceConfiguration)

The current voice configuration for this number. During scheduled provisioning, the app ID, service ID, or trunk ID value may be empty in a response if it is still processing or if it has failed. The status of scheduled provisioning will show under a scheduledVoiceProvisioning object if it's still running. Once processed successfully, the appId/serviceId/trunkId sent will appear directly under the voiceConfiguration object.

callbackUrlstring

The callback URL to be called for a rented number's provisioning / deprovisioning operations.

Example: "https://www.your-callback-server.com/callback"
Response
application/json
{
  "phoneNumber": "+12025550134",
  "projectId": "51bc3f40-f266-4ca8-8938-a1ed0ff32b9a",
  "displayName": "MyPhoneNumber",
  "regionCode": "US",
  "type": "MOBILE",
  "capability": [
    "SMS",
    "VOICE"
  ],
  "money": {
    "currencyCode": "USD",
    "amount": "2.00"
  },
  "paymentIntervalMonths": 0,
  "nextChargeDate": "2024-08-24T14:15:22Z",
  "expireAt": "2024-09-24T14:15:22Z",
  "smsConfiguration": {
    "servicePlanId": "YOUR_service_plan_id",
    "scheduledProvisioning": { … },
    "campaignId": "YOUR_campaign_id"
  },
  "voiceConfiguration": {
    "type": "RTC",
    "lastUpdatedTime": "2024-09-24T14:15:22Z",
    "scheduledVoiceProvisioning": { … },
    "appId": "YOUR_app_id"
  }
}

Rent any number that matches the criteria

Request

Activates a phone number that matches the search criteria provided in the request. Currently the rentAny operation works only for US LOCAL numbers

Security
Basic or OAuth2.0
Path
projectIdstringrequired

Found on your Sinch Customer Dashboard. Settings > Projects.

Example: YOUR_projectId
Bodyapplication/jsonrequired

The request to search and rent a number that matches the criteria.

regionCodestringrequired

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

typestring(Type)required

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.

numberPatternobject(Search Pattern)
capabilitiesArray of strings(Capability)

Number capabilities to filter by, SMS and/or VOICE.

Items Enum ValueDescription
SMS

The SMS product can use the number.

VOICE

The Voice product can use the number.

smsConfigurationobject(SMS Configuration)

The current SMS configuration for this number.

Once the servicePlanId is sent, it enters scheduled provisioning.

The status of scheduled provisioning will show under a scheduledProvisioning object if it's still running. Once processed successfully, the servicePlanId sent will appear directly under the smsConfiguration object.

voiceConfigurationobject(VoiceConfiguration)

The current voice configuration for this number. During scheduled provisioning, the app ID, service ID, or trunk ID value may be empty in a response if it is still processing or if it has failed. The status of scheduled provisioning will show under a scheduledVoiceProvisioning object if it's still running. Once processed successfully, the appId/serviceId/trunkId sent will appear directly under the voiceConfiguration object.

callbackUrlstring

The callback URL to be called for a rented number's provisioning / deprovisioning operations.

Example: "https://www.your-callback-server.com/callback"
curl -i -X POST \
  -u <username>:<password> \
  https://numbers.api.sinch.com/v1/projects/YOUR_projectId/availableNumbers:rentAny \
  -H 'Content-Type: application/json' \
  -d '{
    "regionCode": "US",
    "type": "LOCAL",
    "capabilities": [
      "SMS"
    ],
    "numberPattern": {
      "pattern": "+1208",
      "searchPattern": "START"
    },
    "smsConfiguration": {
      "servicePlanId": "YOUR_SMS_servicePlanId",
      "campaignId": "YOUR_campaignId_from_TCR"
    },
    "callbackUrl": "https://www.your-callback-server.com/callback"
  }'

Responses

A successful response, or an error.

Bodyapplication/json
phoneNumberstring

The phone number in E.164 format with leading +. Example: +12025550134.

Example: "+12025550134"
projectIdstring

Project ID. Your project ID can be found on your Sinch Customer Dashboard.

Example: "51bc3f40-f266-4ca8-8938-a1ed0ff32b9a"
displayNamestring

User supplied name for the phone number.

regionCodestringread-only

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

Example: "US"
typestring(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.

capabilityArray of strings(Capability)

The capability of the number.

Items Enum ValueDescription
SMS

The SMS product can use the number.

VOICE

The Voice product can use the number.

Example: ["SMS"]
moneyobject(Money)

An object giving details on currency code and the amount charged.

paymentIntervalMonthsinteger(int32)read-only

How often the recurring price is charged in months.

nextChargeDatestring(date-time)read-only

The date of the next charge.

expireAtstring(date-time)read-only

The timestamp when the subscription will expire if an expiration date has been set.

smsConfigurationobject(SMS Configuration)

The current SMS configuration for this number.

Once the servicePlanId is sent, it enters scheduled provisioning.

The status of scheduled provisioning will show under a scheduledProvisioning object if it's still running. Once processed successfully, the servicePlanId sent will appear directly under the smsConfiguration object.

voiceConfigurationobject(VoiceConfiguration)

The current voice configuration for this number. During scheduled provisioning, the app ID, service ID, or trunk ID value may be empty in a response if it is still processing or if it has failed. The status of scheduled provisioning will show under a scheduledVoiceProvisioning object if it's still running. Once processed successfully, the appId/serviceId/trunkId sent will appear directly under the voiceConfiguration object.

callbackUrlstring

The callback URL to be called for a rented number's provisioning / deprovisioning operations.

Example: "https://www.your-callback-server.com/callback"
Response
application/json
{
  "phoneNumber": "+12025550134",
  "projectId": "51bc3f40-f266-4ca8-8938-a1ed0ff32b9a",
  "displayName": "string",
  "regionCode": "US",
  "type": "MOBILE",
  "capability": [
    "SMS"
  ],
  "money": {
    "currencyCode": "USD",
    "amount": "2.00"
  },
  "paymentIntervalMonths": 0,
  "nextChargeDate": "2019-08-24T14:15:22Z",
  "expireAt": "2019-08-24T14:15:22Z",
  "smsConfiguration": {
    "servicePlanId": "string",
    "campaignId": "string",
    "scheduledProvisioning": { … }
  },
  "voiceConfiguration": {
    "type": "RTC",
    "lastUpdatedTime": "2019-08-24T14:15:22Z",
    "scheduledVoiceProvisioning": { … },
    "appId": "string"
  },
  "callbackUrl": "https://www.your-callback-server.com/callback"
}

Search for available phone numbers

Request

Search for available phone numbers that are available for you to activate. You can filter by any property on the available number resource.

When searching, indicate the capability of the number in the array as SMS and/or VOICE. To search for a number capable of both, list both SMS and VOICE.

Security
Basic or OAuth2.0
Path
projectIdstringrequired

Found on your Sinch Customer Dashboard. Settings > Projects.

Example: YOUR_projectId
Query
regionCodestringrequired

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

Example: regionCode=US
typestring(Type)required

Number type to filter by. Options include, MOBILE, LOCAL or TOLL_FREE.

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.

numberPattern.patternstring

Sequence of digits to search for. If you prefer or need certain digits in sequential order, you can enter the sequence of numbers here. For example, 2020.

numberPattern.searchPatternstring(Search Pattern)

Search pattern to apply. The options are, START, CONTAINS, and END.

Enum ValueDescription
START

Numbers that start with the provided sequence of digits.

CONTAINS

Numbers that contain the sequence of digits entered.

END

Numbers that end with the sequence of digits entered.

capabilitiesArray of strings(Capability)

Number capabilities to filter by SMS and/or VOICE.

Items Enum ValueDescription
SMS

The SMS product can use the number.

VOICE

The Voice product can use the number.

sizeinteger(int32)

Optional. The maximum number of items to return.

Example: size=3
curl -i -X GET \
  -u <username>:<password> \
  'https://numbers.api.sinch.com/v1/projects/YOUR_projectId/availableNumbers?regionCode=US&type=MOBILE&numberPattern.pattern=string&numberPattern.searchPattern=START&capabilities=SMS&size=3'

Responses

A successful response, or an Error.

Bodyapplication/json
availableNumbersArray of objects(Available Number)

List of available phone numbers.

Response
application/json
{
  "availableNumbers": [
    { … }
  ]
}

Search for a specific phone number

Request

This endpoint allows you to enter a specific phone number to check if it's available for use. A 200 response will return the number's capability, setup costs, monthly costs and if supporting documentation is required.

Security
Basic or OAuth2.0
Path
projectIdstringrequired

Found on your Sinch Customer Dashboard. Settings > Projects.

Example: YOUR_projectId
phoneNumberstringrequired

Output only. The phone number in E.164 format with leading +.

Default "YOUR_selected_phoneNumber_from_search"
Example: +12025550134
curl -i -X GET \
  -u <username>:<password> \
  'https://numbers.api.sinch.com/v1/projects/YOUR_projectId/availableNumbers/+12025550134'

Responses

A successful response.

Bodyapplication/json
phoneNumberstringread-only

The phone number in E.164 format with leading +. Example +12025550134.

Example: "+12025550134"
regionCodestringread-only

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

Example: "US"
typestring(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.

capabilityArray of strings(Capability)

The capability of the number.

Items Enum ValueDescription
SMS

The SMS product can use the number.

VOICE

The Voice product can use the number.

Example: ["SMS","VOICE"]
setupPriceobject(Money)

An object giving details on currency code and the amount charged.

monthlyPriceobject(Money)

An object giving details on currency code and the amount charged.

paymentIntervalMonthsinteger(int32)read-only

How often the recurring price is charged in months.

supportingDocumentationRequiredbooleanread-only

Whether or not supplementary documentation will be required to complete the number rental.

Response
application/json
{
  "phoneNumber": "+12025550134",
  "regionCode": "US",
  "type": "MOBILE",
  "capability": [
    "SMS",
    "VOICE"
  ],
  "setupPrice": {
    "currencyCode": "USD",
    "amount": "2.00"
  },
  "monthlyPrice": {
    "currencyCode": "USD",
    "amount": "2.00"
  },
  "paymentIntervalMonths": 0,
  "supportingDocumentationRequired": true
}

Active Number

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
OperationsWebhooks