You can use the Available Number API to search for available numbers or activate an 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.
Let's take a brief look at some of the formats used in the REST API.
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 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.
Only phone numbers in E.164 standard format are accepted by the API.
A summary of status codes can be found on the HTTP status codes page.
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 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.
Found on your Sinch Customer Dashboard. Settings > Projects.
Region code to filter by. ISO 3166-1 alpha-2 country code of the phone number. Example: US, GB or SE.
Number type to filter by. Options include, MOBILE, LOCAL or TOLL_FREE.
| Enum Value | Description |
|---|---|
| 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. |
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.
Search pattern to apply. The options are, START, CONTAINS, and END.
| Enum Value | Description |
|---|---|
| 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. |
Number capabilities to filter by SMS and/or VOICE.
| Items Enum Value | Description |
|---|---|
| SMS | The SMS product can use the number. |
| VOICE | The Voice product can use the number. |
- Global APIhttps://numbers.api.sinch.com/v1/projects/{projectId}/activeNumbers
- curl
- JavaScript
- Node.js
- Python
- Java
- C#
- PHP
- Go
- Ruby
- R
- Payload
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'A successful response, or an Error.
List of numbers associated to the client project specified in ListActiveNumbers.
{ "activeNumbers": [ { … } ], "nextPageToken": "string", "totalSize": 0 }
Request
Update an active phone number. You can perform the following updates:
- Update the name that displays for a customer by modifying the
displayNameparameter. - Unlink the number from an SMS service or campaign by updating the
smsConfigurationconfiguration 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.
Found on your Sinch Customer Dashboard. Settings > Projects.
Output only. The phone number in E.164 format with leading +.
The number body to be updated.
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.
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.
- Global APIhttps://numbers.api.sinch.com/v1/projects/{projectId}/activeNumbers/{phoneNumber}
- curl
- JavaScript
- Node.js
- Python
- Java
- C#
- PHP
- Go
- Ruby
- R
- Payload
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"
}'A successful response, or an Error.
The phone number in E.164 format with leading +. Example: +12025550134.
Project ID. Your project ID can be found on your Sinch Customer Dashboard.
ISO 3166-1 alpha-2 country code of the phone number. Example US, UK or SE.
The number type.
| Enum Value | Description |
|---|---|
| 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. |
The capability of the number.
| Items Enum Value | Description |
|---|---|
| SMS | The SMS product can use the number. |
| VOICE | The Voice product can use the number. |
The timestamp when the subscription will expire if an expiration date has been set.
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.
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.
{ "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" } }
Found on your Sinch Customer Dashboard. Settings > Projects.
Output only. The phone number in E.164 format with leading +.
- Global APIhttps://numbers.api.sinch.com/v1/projects/{projectId}/activeNumbers/{phoneNumber}
- curl
- JavaScript
- Node.js
- Python
- Java
- C#
- PHP
- Go
- Ruby
- R
- Payload
curl -i -X GET \
-u <username>:<password> \
'https://numbers.api.sinch.com/v1/projects/YOUR_projectId/activeNumbers/+12025550134'A successful response, or an Error.
The phone number in E.164 format with leading +. Example: +12025550134.
Project ID. Your project ID can be found on your Sinch Customer Dashboard.
ISO 3166-1 alpha-2 country code of the phone number. Example US, UK or SE.
The number type.
| Enum Value | Description |
|---|---|
| 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. |
The capability of the number.
| Items Enum Value | Description |
|---|---|
| SMS | The SMS product can use the number. |
| VOICE | The Voice product can use the number. |
The timestamp when the subscription will expire if an expiration date has been set.
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.
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.
{ "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" } }
Found on your Sinch Customer Dashboard. Settings > Projects.
Output only. The phone number in E.164 format with leading +.
- Global APIhttps://numbers.api.sinch.com/v1/projects/{projectId}/activeNumbers/{phoneNumber}:release
- curl
- JavaScript
- Node.js
- Python
- Java
- C#
- PHP
- Go
- Ruby
- R
- Payload
curl -i -X POST \
-u <username>:<password> \
'https://numbers.api.sinch.com/v1/projects/YOUR_projectId/activeNumbers/+12025550134:release'A successful response, or an Error.
The phone number in E.164 format with leading +. Example: +12025550134.
Project ID. Your project ID can be found on your Sinch Customer Dashboard.
ISO 3166-1 alpha-2 country code of the phone number. Example US, UK or SE.
The number type.
| Enum Value | Description |
|---|---|
| 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. |
The capability of the number.
| Items Enum Value | Description |
|---|---|
| SMS | The SMS product can use the number. |
| VOICE | The Voice product can use the number. |
The timestamp when the subscription will expire if an expiration date has been set.
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.
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.
{ "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" } }
Found on your Sinch Customer Dashboard. Settings > Projects.
Output only. The phone number in E.164 format with leading +.
- Global APIhttps://numbers.api.sinch.com/v1/projects/{projectId}/activeNumbers/{phoneNumber}/emergencyAddress
- curl
- JavaScript
- Node.js
- Python
- Java
- C#
- PHP
- Go
- Ruby
- R
- Payload
curl -i -X GET \
-u <username>:<password> \
'https://numbers.api.sinch.com/v1/projects/YOUR_projectId/activeNumbers/+12025550134/emergencyAddress'A successful response, or an error
{ "streetNumber": "12345", "streetInfo": "Main St", "location": "Apt 5", "city": "Springfield", "state": "IL", "postalCode": "62701", "postalCodePlusFour": "1234" }
Found on your Sinch Customer Dashboard. Settings > Projects.
Output only. The phone number in E.164 format with leading +.
Request to provision an emergency address for a number.
Details of the emergency address.
- Global APIhttps://numbers.api.sinch.com/v1/projects/{projectId}/activeNumbers/{phoneNumber}/emergencyAddress:provision
- curl
- JavaScript
- Node.js
- Python
- Java
- C#
- PHP
- Go
- Ruby
- R
- Payload
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"
}
}'A successful response, or an error
{ "streetNumber": "12345", "streetInfo": "Main St", "location": "Apt 5", "city": "Springfield", "state": "IL", "postalCode": "62701", "postalCodePlusFour": "1234" }
Found on your Sinch Customer Dashboard. Settings > Projects.
Output only. The phone number in E.164 format with leading +.
- Global APIhttps://numbers.api.sinch.com/v1/projects/{projectId}/activeNumbers/{phoneNumber}/emergencyAddress:deprovision
- curl
- JavaScript
- Node.js
- Python
- Java
- C#
- PHP
- Go
- Ruby
- R
- Payload
curl -i -X POST \
-u <username>:<password> \
'https://numbers.api.sinch.com/v1/projects/YOUR_projectId/activeNumbers/+12025550134/emergencyAddress:deprovision'A successful response, or an error
No contentFound on your Sinch Customer Dashboard. Settings > Projects.
Output only. The phone number in E.164 format with leading +.
Request to validate an emergency address for a number.
Details of the emergency address.
- Global APIhttps://numbers.api.sinch.com/v1/projects/{projectId}/activeNumbers/{phoneNumber}/emergencyAddress:validate
- curl
- JavaScript
- Node.js
- Python
- Java
- C#
- PHP
- Go
- Ruby
- R
- Payload
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"
}
}'A successful response, or an error
Enum representing the result of address validation.
| Enum Value | Description |
|---|---|
| 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 |
{ "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": [] }
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