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.

Lists active numbers for a project

Lists all active numbers for a project.

SecurityBasic or OAuth2.0
Request
path Parameters
projectId
required
string

Found on your Sinch Customer Dashboard. Settings > Projects.

Example: YOUR_projectId
query Parameters
regionCode
required
string

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

Example: regionCode=US
type
required
string

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

Enum: Description
MOBILE

Numbers that belong to a specific range.

LOCAL

Numbers that are assigned to a specific geographic region.

TOLL_FREE

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

Example: type=LOCAL
numberPattern.pattern
string

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.searchPattern
string

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

Enum: Description
START

Numbers that begin with the numberPattern.pattern entered. Often used to search for a specific area code. When using START, a plus sign (+) must be included and URL encoded, so %2B. For example, to search for area code 206 in the US, you would enter, %2b1206.

CONTAINS

The number pattern entered is contained somewhere in the number, the location being undefined.

END

The number ends with the number pattern entered.

capability
Array of strings

Number capabilities to filter by SMS and/or VOICE.

Items Enum: Description
SMS

The SMS product can use the number.

VOICE

The Voice product can use the number.

pageSize
integer <int32>

The maximum number of items to return.

pageToken
string

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

orderBy
string

Supported fields for ordering by phoneNumber or displayName.

Responses
200

A successful response.

Response Schema: application/json
Array of objects (Active Number Response)

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

Array
phoneNumber
string

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

projectId
string

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

displayName
string

User supplied name for the phone number.

regionCode
string

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

type
string (Type)
Default: "MOBILE"

The number type.

Enum: 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.

capability
Array of strings (Capability)

The capability of the number.

Items Enum: Description
SMS

The SMS product can use the number.

VOICE

The Voice product can use the number.

object (Money)

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

paymentIntervalMonths
integer <int32>

How often the recurring price is charged in months.

nextChargeDate
string <date-time>

The date of the next charge.

expireAt
string <date-time>

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

object (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.

object (Voice Configuration)

The current voice configuration for this number.

During scheduled provisioning, the app 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 scheduledProvisioning object if it's still running. Once processed successfully, the appId sent will appear directly under the voiceConfiguration object.

callbackUrl
string

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

nextPageToken
string (The token to be used for listing the next page.)
totalSize
integer <int32> (The maximum number of results returned.)
400

400 Invalid Argument error

404

404 Not Found error

500

500 Internal Server error

get/v1/projects/{projectId}/activeNumbers
Request samples 
Response samples 
application/json
{
  • "activeNumbers": [
    • {
      }
    ],
  • "nextPageToken": "string",
  • "totalSize": 0
}
Update an active phone number
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.


SecurityBasic or OAuth2.0 
Request 
path Parameters
projectId
required
string
Found on your Sinch Customer Dashboard. Settings > Projects.


 
 Example:  YOUR_projectId
phoneNumber
required
string
 Default:  "YOUR_selected_phoneNumber_from_search"
Output only. The phone number in E.164 format with leading +.


 
 Example:  +12025550134
Request Body schema: application/json
The number body to be updated.


displayName
string
User supplied name for the phone number.


 
object (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.


 
servicePlanId
required
string
The servicePlanId can be found in the Sinch Customer Dashboard. The service plan ID is what ties this number to the configured SMS service.


 
campaignId
string
Only for US phone numbers. This campaignId is required to send SMS traffic to US; click here to read more about 10DLC A2P messaging. So, it is the current campaign ID for this number. The campaignId is found on your TCR platform.


 
object (Voice Configuration) 
The current voice configuration for this number. During scheduled provisioning, the app 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 sent will appear directly under the voiceConfiguration object.


 
appId
string
Your app ID for the Voice API. The appId can be found in your Sinch Customer Dashboard under Voice, then apps.


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


 
Responses 
200
A successful response, or an Error.


Response Schema: application/json
phoneNumber
string
The phone number in E.164 format with leading +. Example: +12025550134.


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


 
displayName
string
User supplied name for the phone number.


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


 
type
string (Type) 
 Default:  "MOBILE"
The number type.


 Enum: 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.


 
capability
Array of strings (Capability) 
The capability of the number.


Items Enum: Description
SMS
The SMS product can use the number.


VOICE
The Voice product can use the number.


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


 
currencyCode
string
The 3-letter currency code defined in ISO 4217.


 
amount
string
The amount in decimal form.
For example 2.00.
There are no guarantees on the precision unless documented by the message origin. The amount cannot be updated and is read-only.


 
paymentIntervalMonths
integer <int32> 
How often the recurring price is charged in months.


 
nextChargeDate
string <date-time> 
The date of the next charge.


 
expireAt
string <date-time> 
The timestamp when the subscription will expire if an expiration date has been set.


 
object (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.


 
servicePlanId
string
The servicePlanId can be found in the Sinch Customer Dashboard. The service plan ID is what ties this to the configured SMS service.


 
object (Scheduled SMS Provisioning) 
This object is temporary and will appear while the scheduled provisioning for SMS is processing. Once it has successfully processed, only the ID of the SMS configuration will display.


 
servicePlanId
string
Service plan of the scheduled provisioning task.


 
status
any (Provisioning Status) 
 Default:  "WAITING"
The provisioning status. It will be either WAITING, IN_PROGRESS or FAILED. If the provisioning fails, a reason for the failure will be provided. See a full list of provisioning error descriptions and troubleshooting recommendations.


 Enum: "WAITING" "IN_PROGRESS" "FAILED"  
lastUpdatedTime
string <date-time> 
Timestamp when the status was last updated.


 
campaignId
string
Campaign ID of the scheduled provisioning task. Note that the campaign ID is only for US numbers as it relates to 10DLC.


 
errorCodes
Array of strings (Type) 
The provisioning status codes are found here. 


 
campaignId
string
Only for US phone numbers. This campaignId is required to send SMS traffic to US; click here to read more about 10DLC A2P messaging. So, it is the current campaign ID for this number. The campaignId is found on your TCR platform. 


 
object (Voice Configuration) 
The current voice configuration for this number. 


During scheduled provisioning, the app 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 scheduledProvisioning object if it's still running. Once processed successfully, the appId sent will appear directly under the voiceConfiguration object.


 
appId
string
Your app ID for the Voice API. The appId can be found in your Sinch Customer Dashboard under Voice, then apps.


 
object (Scheduled Voice Provisioning) 
This object is temporary and will appear while the scheduled voice provisioning is processing. Once it has successfully processed, only the ID of the Voice configuration will display.


 
appId
string
RTC application ID of the scheduled provisioning task.


 
status
any (Provisioning Status) 
 Default:  "WAITING"
The provisioning status. It will be either WAITING, IN_PROGRESS or FAILED. If the provisioning fails, a reason for the failure will be provided. See a full list of provisioning error descriptions and troubleshooting recommendations.


 Enum: "WAITING" "IN_PROGRESS" "FAILED"  
lastUpdatedTime
string <date-time> 
Timestamp when the status was last updated.


 
lastUpdatedTime
string <date-time> 
Timestamp when the status was last updated.


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


 
400
400 Invalid Argument error


404
404 Not Found error


500
500 Internal Server error


patch/v1/projects/{projectId}/activeNumbers/{phoneNumber}
Request samples 
application/json
{
  • "displayName": "MyPhoneNumber",
  • "smsConfiguration": {
    • "servicePlanId": "string",
    • "campaignId": "YOUR_campaignId_from_TCR"
    },
  • "voiceConfiguration": {
    • "appId": "YOUR_Voice_appId"
    },
  • "callbackUrl": "https://www.your-callback-server.com/callback"
}
Response samples 
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",
    • "scheduledProvisioning": {
      },
    • "campaignId": "string"
    },
  • "voiceConfiguration": {
    • "appId": "string",
    • "scheduledVoiceProvisioning": {
      },
    • "lastUpdatedTime": "2019-08-24T14:15:22Z"
    },
  • "callbackUrl": "https://www.your-callback-server.com/callback"
}
Retrieve an active phone number
SecurityBasic or OAuth2.0 
Request 
path Parameters
projectId
required
string
Found on your Sinch Customer Dashboard. Settings > Projects.


 
 Example:  YOUR_projectId
phoneNumber
required
string
 Default:  "YOUR_selected_phoneNumber_from_search"
Output only. The phone number in E.164 format with leading +.


 
 Example:  +12025550134
Responses 
200
A successful response, or an Error.


Response Schema: application/json
phoneNumber
string
The phone number in E.164 format with leading +. Example: +12025550134.


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


 
displayName
string
User supplied name for the phone number.


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


 
type
string (Type) 
 Default:  "MOBILE"
The number type.


 Enum: 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.


 
capability
Array of strings (Capability) 
The capability of the number.


Items Enum: Description
SMS
The SMS product can use the number.


VOICE
The Voice product can use the number.


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


 
currencyCode
string
The 3-letter currency code defined in ISO 4217.


 
amount
string
The amount in decimal form.
For example 2.00.
There are no guarantees on the precision unless documented by the message origin. The amount cannot be updated and is read-only.


 
paymentIntervalMonths
integer <int32> 
How often the recurring price is charged in months.


 
nextChargeDate
string <date-time> 
The date of the next charge.


 
expireAt
string <date-time> 
The timestamp when the subscription will expire if an expiration date has been set.


 
object (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.


 
servicePlanId
string
The servicePlanId can be found in the Sinch Customer Dashboard. The service plan ID is what ties this to the configured SMS service.


 
object (Scheduled SMS Provisioning) 
This object is temporary and will appear while the scheduled provisioning for SMS is processing. Once it has successfully processed, only the ID of the SMS configuration will display.


 
servicePlanId
string
Service plan of the scheduled provisioning task.


 
status
any (Provisioning Status) 
 Default:  "WAITING"
The provisioning status. It will be either WAITING, IN_PROGRESS or FAILED. If the provisioning fails, a reason for the failure will be provided. See a full list of provisioning error descriptions and troubleshooting recommendations.


 Enum: "WAITING" "IN_PROGRESS" "FAILED"  
lastUpdatedTime
string <date-time> 
Timestamp when the status was last updated.


 
campaignId
string
Campaign ID of the scheduled provisioning task. Note that the campaign ID is only for US numbers as it relates to 10DLC.


 
errorCodes
Array of strings (Type) 
The provisioning status codes are found here. 


 
campaignId
string
Only for US phone numbers. This campaignId is required to send SMS traffic to US; click here to read more about 10DLC A2P messaging. So, it is the current campaign ID for this number. The campaignId is found on your TCR platform. 


 
object (Voice Configuration) 
The current voice configuration for this number. 


During scheduled provisioning, the app 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 scheduledProvisioning object if it's still running. Once processed successfully, the appId sent will appear directly under the voiceConfiguration object.


 
appId
string
Your app ID for the Voice API. The appId can be found in your Sinch Customer Dashboard under Voice, then apps.


 
object (Scheduled Voice Provisioning) 
This object is temporary and will appear while the scheduled voice provisioning is processing. Once it has successfully processed, only the ID of the Voice configuration will display.


 
appId
string
RTC application ID of the scheduled provisioning task.


 
status
any (Provisioning Status) 
 Default:  "WAITING"
The provisioning status. It will be either WAITING, IN_PROGRESS or FAILED. If the provisioning fails, a reason for the failure will be provided. See a full list of provisioning error descriptions and troubleshooting recommendations.


 Enum: "WAITING" "IN_PROGRESS" "FAILED"  
lastUpdatedTime
string <date-time> 
Timestamp when the status was last updated.


 
lastUpdatedTime
string <date-time> 
Timestamp when the status was last updated.


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


 
400
400 Invalid Argument error


404
404 Not Found error


500
500 Internal Server error


get/v1/projects/{projectId}/activeNumbers/{phoneNumber}
Request samples 
Response samples 
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",
    • "scheduledProvisioning": {
      },
    • "campaignId": "string"
    },
  • "voiceConfiguration": {
    • "appId": "string",
    • "scheduledVoiceProvisioning": {
      },
    • "lastUpdatedTime": "2019-08-24T14:15:22Z"
    },
  • "callbackUrl": "https://www.your-callback-server.com/callback"
}
Release an active number from the project
With this endpoint, you can cancel your subscription for a specific phone number.


SecurityBasic or OAuth2.0 
Request 
path Parameters
projectId
required
string
Found on your Sinch Customer Dashboard. Settings > Projects.


 
 Example:  YOUR_projectId
phoneNumber
required
string
 Default:  "YOUR_selected_phoneNumber_from_search"
Output only. The phone number in E.164 format with leading +.


 
 Example:  +12025550134
Responses 
200
A successful response, or an Error.


Response Schema: application/json
phoneNumber
string
The phone number in E.164 format with leading +. Example: +12025550134.


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


 
displayName
string
User supplied name for the phone number.


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


 
type
string (Type) 
 Default:  "MOBILE"
The number type.


 Enum: 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.


 
capability
Array of strings (Capability) 
The capability of the number.


Items Enum: Description
SMS
The SMS product can use the number.


VOICE
The Voice product can use the number.


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


 
currencyCode
string
The 3-letter currency code defined in ISO 4217.


 
amount
string
The amount in decimal form.
For example 2.00.
There are no guarantees on the precision unless documented by the message origin. The amount cannot be updated and is read-only.


 
paymentIntervalMonths
integer <int32> 
How often the recurring price is charged in months.


 
nextChargeDate
string <date-time> 
The date of the next charge.


 
expireAt
string <date-time> 
The timestamp when the subscription will expire if an expiration date has been set.


 
object (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.


 
servicePlanId
string
The servicePlanId can be found in the Sinch Customer Dashboard. The service plan ID is what ties this to the configured SMS service.


 
object (Scheduled SMS Provisioning) 
This object is temporary and will appear while the scheduled provisioning for SMS is processing. Once it has successfully processed, only the ID of the SMS configuration will display.


 
servicePlanId
string
Service plan of the scheduled provisioning task.


 
status
any (Provisioning Status) 
 Default:  "WAITING"
The provisioning status. It will be either WAITING, IN_PROGRESS or FAILED. If the provisioning fails, a reason for the failure will be provided. See a full list of provisioning error descriptions and troubleshooting recommendations.


 Enum: "WAITING" "IN_PROGRESS" "FAILED"  
lastUpdatedTime
string <date-time> 
Timestamp when the status was last updated.


 
campaignId
string
Campaign ID of the scheduled provisioning task. Note that the campaign ID is only for US numbers as it relates to 10DLC.


 
errorCodes
Array of strings (Type) 
The provisioning status codes are found here. 


 
campaignId
string
Only for US phone numbers. This campaignId is required to send SMS traffic to US; click here to read more about 10DLC A2P messaging. So, it is the current campaign ID for this number. The campaignId is found on your TCR platform. 


 
object (Voice Configuration) 
The current voice configuration for this number. 


During scheduled provisioning, the app 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 scheduledProvisioning object if it's still running. Once processed successfully, the appId sent will appear directly under the voiceConfiguration object.


 
appId
string
Your app ID for the Voice API. The appId can be found in your Sinch Customer Dashboard under Voice, then apps.


 
object (Scheduled Voice Provisioning) 
This object is temporary and will appear while the scheduled voice provisioning is processing. Once it has successfully processed, only the ID of the Voice configuration will display.


 
appId
string
RTC application ID of the scheduled provisioning task.


 
status
any (Provisioning Status) 
 Default:  "WAITING"
The provisioning status. It will be either WAITING, IN_PROGRESS or FAILED. If the provisioning fails, a reason for the failure will be provided. See a full list of provisioning error descriptions and troubleshooting recommendations.


 Enum: "WAITING" "IN_PROGRESS" "FAILED"  
lastUpdatedTime
string <date-time> 
Timestamp when the status was last updated.


 
lastUpdatedTime
string <date-time> 
Timestamp when the status was last updated.


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


 
400
400 Invalid Argument error


404
404 Not Found error


500
500 Internal Server error


post/v1/projects/{projectId}/activeNumbers/{phoneNumber}:release
Request samples 
Response samples 
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",
    • "scheduledProvisioning": {
      },
    • "campaignId": "string"
    },
  • "voiceConfiguration": {
    • "appId": "string",
    • "scheduledVoiceProvisioning": {
      },
    • "lastUpdatedTime": "2019-08-24T14:15:22Z"
    },
  • "callbackUrl": "https://www.your-callback-server.com/callback"
}
SecurityPrivacyLegal & ComplianceCookie Statement
© 2024 Sinch. All rights reserved.