Skip to content

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
Overview
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

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

Lists active numbers for a project

Request

Lists all active numbers for a project.

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.

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

pageSizeinteger(int32)

The maximum number of items to return.

pageTokenstring

The next page token value returned from a previous List request, if any.

orderBystring

Supported fields for ordering by phoneNumber or displayName.

Enum ValueDescription
phoneNumber

Ordered by phone number

displayName

Ordered by display name

curl -i -X GET \
  -u <username>:<password> \
  'https://numbers.api.sinch.com/v1/projects/YOUR_projectId/activeNumbers?regionCode=US&type=MOBILE&numberPattern.pattern=string&numberPattern.searchPattern=START&capability=SMS&pageSize=0&pageToken=string&orderBy=phoneNumber'

Responses

A successful response, or an Error.

Bodyapplication/json
activeNumbersArray of objects(Active Number Response)

List of numbers associated to the client project specified in ListActiveNumbers.

nextPageTokenstring(The token to be used for listing the next page.)
totalSizeinteger(int32)(The maximum number of results returned.)
Response
application/json
{ "activeNumbers": [ {} ], "nextPageToken": "string", "totalSize": 0 }

Update an active phone number

Request

Update an active phone number. You can perform the following updates:

  • Update the name that displays for a customer by modifying the displayName parameter.
  • Unlink the number from an SMS service or campaign by updating the smsConfiguration configuration object. To unlink a number, submit the request with an empty string (””) in the service plan ID or campaign ID fields.
  • Before linking a number to a new service or campaign, it must be unlinked from any existing service or campaign. Then, link the number to a new SMS service or campaign by updating the service plan ID or campaign ID with the new desired value.
  • Update the Voice app to which the number is assigned by using the voiceConfiguration object.

You can update both SMS and Voice in the same object by including both configuration objects. If you only need to update either Voice or SMS, simply omit the other object. If you pass an empty configuration object, the request will fail.

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/json

The number body to be updated.

displayNamestring

User supplied name for the phone 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 PATCH \
  -u <username>:<password> \
  'https://numbers.api.sinch.com/v1/projects/YOUR_projectId/activeNumbers/+12025550134' \
  -H 'Content-Type: application/json' \
  -d '{
    "displayName": "MyPhoneNumber",
    "smsConfiguration": {
      "servicePlanId": "string",
      "campaignId": "YOUR_campaignId_from_TCR"
    },
    "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" } }

Retrieve an active phone number

Request

Retrieve a specific active phone number.

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/activeNumbers/+12025550134'

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

Release an active number from the project

Request

With this endpoint, you can cancel your subscription for a specific phone number.

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 POST \
  -u <username>:<password> \
  'https://numbers.api.sinch.com/v1/projects/YOUR_projectId/activeNumbers/+12025550134:release'

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

Get the emergency address for a number

Request

With this endpoint, you can retrieve the emergency address associated with this number.

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/activeNumbers/+12025550134/emergencyAddress'

Responses

A successful response, or an error

Bodyapplication/json
streetNumberstring

The street number for the emergency address.

Example: "12345"
streetInfostring

The street name of the emergency location.

Example: "Main St"
locationstring

The location for address.

Example: "Apt 5"
citystring

The city of the emergency location.

Example: "Springfield"
statestring

The state or province of the emergency location.

Example: "IL"
postalCodestring

The postal code of the emergency location.

Example: "62701"
postalCodePlusFourstring

The postal code of the emergency location.

Example: "1234"
Response
application/json
{ "streetNumber": "12345", "streetInfo": "Main St", "location": "Apt 5", "city": "Springfield", "state": "IL", "postalCode": "62701", "postalCodePlusFour": "1234" }

Add a emergency address for a number

Request

With this endpoint, you can provision an emergency address associated with this number.

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/json

Request to provision an emergency address for a number.

displayNamestringrequired

Name for emergency address.

Example: "New emergency address"
addressobject(Emergency Address)required

Details of the emergency address.

address.​streetNumberstringrequired

The street number for the emergency address.

Example: "12345"
address.​streetInfostringrequired

The street name of the emergency location.

Example: "Main St"
address.​citystringrequired

The city of the emergency location.

Example: "Springfield"
address.​statestringrequired

The state or province of the emergency location.

Example: "IL"
address.​postalCodestringrequired

The postal code of the emergency location.

Example: "62701"
address.​locationstring

The location for address.

Example: "Apt 5"
address.​postalCodePlusFourstring

The postal code of the emergency location.

Example: "1234"
curl -i -X POST \
  -u <username>:<password> \
  'https://numbers.api.sinch.com/v1/projects/YOUR_projectId/activeNumbers/+12025550134/emergencyAddress:provision' \
  -H 'Content-Type: application/json' \
  -d '{
    "displayName": "New Emergency Address",
    "address": {
      "streetNumber": "12345",
      "streetInfo": "Main St",
      "city": "Springfield",
      "state": "IL",
      "postalCode": "62701"
    }
  }'

Responses

A successful response, or an error

Bodyapplication/json
streetNumberstring

The street number for the emergency address.

Example: "12345"
streetInfostring

The street name of the emergency location.

Example: "Main St"
locationstring

The location for address.

Example: "Apt 5"
citystring

The city of the emergency location.

Example: "Springfield"
statestring

The state or province of the emergency location.

Example: "IL"
postalCodestring

The postal code of the emergency location.

Example: "62701"
postalCodePlusFourstring

The postal code of the emergency location.

Example: "1234"
Response
application/json
{ "streetNumber": "12345", "streetInfo": "Main St", "location": "Apt 5", "city": "Springfield", "state": "IL", "postalCode": "62701", "postalCodePlusFour": "1234" }

Remove the emergency address for a number.

Request

With this endpoint, you can deprovision the emergency address associated with this number.

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 POST \
  -u <username>:<password> \
  'https://numbers.api.sinch.com/v1/projects/YOUR_projectId/activeNumbers/+12025550134/emergencyAddress:deprovision'

Responses

A successful response, or an error

Response
No content

Validate the emergency address for a number.

Request

With this endpoint, you can validate the emergency address associated with this number.

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/json

Request to validate an emergency address for a number.

displayNamestringrequired

Name for emergency address.

Example: "New emergency address"
addressobject(Emergency Address)required

Details of the emergency address.

address.​streetNumberstringrequired

The street number for the emergency address.

Example: "12345"
address.​streetInfostringrequired

The street name of the emergency location.

Example: "Main St"
address.​citystringrequired

The city of the emergency location.

Example: "Springfield"
address.​statestringrequired

The state or province of the emergency location.

Example: "IL"
address.​postalCodestringrequired

The postal code of the emergency location.

Example: "62701"
address.​locationstring

The location for address.

Example: "Apt 5"
address.​postalCodePlusFourstring

The postal code of the emergency location.

Example: "1234"
curl -i -X POST \
  -u <username>:<password> \
  'https://numbers.api.sinch.com/v1/projects/YOUR_projectId/activeNumbers/+12025550134/emergencyAddress:validate' \
  -H 'Content-Type: application/json' \
  -d '{
    "displayName": "New Emergency Address",
    "address": {
      "streetNumber": "12345",
      "streetInfo": "Main St",
      "city": "Springfield",
      "state": "IL",
      "postalCode": "62701"
    }
  }'

Responses

A successful response, or an error

Bodyapplication/json
phoneNumberstring

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

Example: "+12025550134"
displayNamestring

User supplied name for the phone number.

Example: "User Name"
validatedAddressobject(Emergency Address)

Details of the emergency address.

validationResultstring(AddressValidationResultCode)

Enum representing the result of address validation.

Enum ValueDescription
ADDRESS_VALIDATION_RESULT_CODE_UNSPECIFIED

Undetermined Result

EXACT_MATCH

The address is perfect as sent

NEAR_MATCH

The result was a close enough match and has been corrected

NO_MATCH

The result is not close enough

validationMessagestring

Validation result message

Example: "Corrected to valid address"
correctedAddressobject(Emergency Address)

Details of the emergency address.

candidateAddressesArray of objects(Emergency Address)

List of candidate addresses (only available if validationResult == NO_MATCH)

Response
application/json
{ "phoneNumber": "+12025550134", "displayName": "User Name", "validatedAddress": { "streetNumber": "12345", "streetInfo": "Main St", "location": "Apt 5", "city": "Springfield", "state": "IL", "postalCode": "62701", "postalCodePlusFour": "1234" }, "validationResult": "EXACT_MATCH", "validationMessage": "Address is a perfect match", "correctedAddress": {}, "candidateAddresses": [] }

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