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 Value 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 Value 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 Value 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, or an Error.

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

capability
Array of strings (Capability)

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.

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

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

403

PERMISSION_DENIED: improper credentials. Be sure your projectId, username and password are correct.

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


 
type
string (VoiceApplicationType) 
 Default:  "RTC"
The voice application type. Examples are RTC, EST, FAX


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


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


 
capability
Array of strings (Capability) 
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.


 
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
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 (Scheduled Provisioning) 
Represents the ongoing or failed scheduled provisioning job. This field will be empty if the number was both successfully provisioned to the SMS platform and linked to the 10DLC campaign.


 
servicePlanId
string
The SMS service plan that the scheduled provisioning job will configure with the number.


 
campaignId
string
TCR campaign ID that the scheduled provisioning job will configure with the number.


 
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]<(https://developers.sinch.com/docs/numbers/api-reference/error-codes/provisioning-errors) and troubleshooting recommendations.


 Enum Value Description
PROVISIONING_STATUS_UNSPECIFIED
The status is currently unknown.


WAITING
Waiting for provisioning


IN_PROGRESS
Provisioning in progress


FAILED
Provisioning failed. See provisioning error descriptions


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


 
errorCodes
Array of strings (SMS Error Code) 
Items Enum Value Description
ERROR_CODE_UNSPECIFIED
Code not specified.


INTERNAL_ERROR
Internal server error.


SMS_PROVISIONING_FAILED
Provisioning for SMS failed.


CAMPAIGN_PROVISIONING_FAILED
Provisioning for campaign failed.


CAMPAIGN_NOT_AVAILABLE
The specified campaign is not available.


EXCEEDED_10DLC_LIMIT
Exceeded the 10DLC limit.


NUMBER_PROVISIONING_FAILED
Failed to provision the number.


PARTNER_SERVICE_UNAVAILABLE
The third party service is unavailable.


CAMPAIGN_PENDING_ACCEPTANCE
The campaign is awaiting acceptance.


MNO_SHARING_ERROR
Sharing error.


CAMPAIGN_EXPIRED
The specific campaign has expired.


CAMPAIGN_MNO_REJECTED
The MNO for the campaign was rejected.


CAMPAIGN_MNO_SUSPENDED
The MNO for the campaign was suspended.


CAMPAIGN_MNO_REVIEW
The MNO for the campaign is under review.


INSUFFICIENT_BALANCE
The credit balance for the account is insufficient to cover the fees.


MOCK_CAMPAIGN_NOT_ALLOWED
Mock campaign is not permitted.


TFN_NOT_ALLOWED
The Toll-Free number is not allowed.


INVALID_NNID
The specified NNID is invalid.


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


 
type
string (VoiceApplicationType) 
 Default:  "RTC"
The voice application type. Examples are RTC, EST, FAX


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


 
object (Scheduled Voice Provisioning) 
Represents the ongoing or failed scheduled voice provisioning job. This field will be empty if the number was successfully provisioned provisioned for voice.


 
type
required
string (VoiceApplicationType) 
 Default:  "RTC"
The voice application type. Examples are RTC, EST, FAX


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


 
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]<(https://developers.sinch.com/docs/numbers/api-reference/error-codes/provisioning-errors) and troubleshooting recommendations.


 Enum Value Description
PROVISIONING_STATUS_UNSPECIFIED
The status is currently unknown.


WAITING
Waiting for provisioning


IN_PROGRESS
Provisioning in progress


FAILED
Provisioning failed. See provisioning error descriptions


 
trunkId
string
The trunk ID if the type is EST. The trunkId can be found in your Sinch Customer Dashboard.


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


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


 
400
400 Invalid Argument error


403
PERMISSION_DENIED: improper credentials. Be sure your projectId, username and password are correct.


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": {
    • "type": "RTC",
    • "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": "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
Retrieve a specific 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 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.


 
capability
Array of strings (Capability) 
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.


 
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
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 (Scheduled Provisioning) 
Represents the ongoing or failed scheduled provisioning job. This field will be empty if the number was both successfully provisioned to the SMS platform and linked to the 10DLC campaign.


 
servicePlanId
string
The SMS service plan that the scheduled provisioning job will configure with the number.


 
campaignId
string
TCR campaign ID that the scheduled provisioning job will configure with the number.


 
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]<(https://developers.sinch.com/docs/numbers/api-reference/error-codes/provisioning-errors) and troubleshooting recommendations.


 Enum Value Description
PROVISIONING_STATUS_UNSPECIFIED
The status is currently unknown.


WAITING
Waiting for provisioning


IN_PROGRESS
Provisioning in progress


FAILED
Provisioning failed. See provisioning error descriptions


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


 
errorCodes
Array of strings (SMS Error Code) 
Items Enum Value Description
ERROR_CODE_UNSPECIFIED
Code not specified.


INTERNAL_ERROR
Internal server error.


SMS_PROVISIONING_FAILED
Provisioning for SMS failed.


CAMPAIGN_PROVISIONING_FAILED
Provisioning for campaign failed.


CAMPAIGN_NOT_AVAILABLE
The specified campaign is not available.


EXCEEDED_10DLC_LIMIT
Exceeded the 10DLC limit.


NUMBER_PROVISIONING_FAILED
Failed to provision the number.


PARTNER_SERVICE_UNAVAILABLE
The third party service is unavailable.


CAMPAIGN_PENDING_ACCEPTANCE
The campaign is awaiting acceptance.


MNO_SHARING_ERROR
Sharing error.


CAMPAIGN_EXPIRED
The specific campaign has expired.


CAMPAIGN_MNO_REJECTED
The MNO for the campaign was rejected.


CAMPAIGN_MNO_SUSPENDED
The MNO for the campaign was suspended.


CAMPAIGN_MNO_REVIEW
The MNO for the campaign is under review.


INSUFFICIENT_BALANCE
The credit balance for the account is insufficient to cover the fees.


MOCK_CAMPAIGN_NOT_ALLOWED
Mock campaign is not permitted.


TFN_NOT_ALLOWED
The Toll-Free number is not allowed.


INVALID_NNID
The specified NNID is invalid.


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


 
type
string (VoiceApplicationType) 
 Default:  "RTC"
The voice application type. Examples are RTC, EST, FAX


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


 
object (Scheduled Voice Provisioning) 
Represents the ongoing or failed scheduled voice provisioning job. This field will be empty if the number was successfully provisioned provisioned for voice.


 
type
required
string (VoiceApplicationType) 
 Default:  "RTC"
The voice application type. Examples are RTC, EST, FAX


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


 
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]<(https://developers.sinch.com/docs/numbers/api-reference/error-codes/provisioning-errors) and troubleshooting recommendations.


 Enum Value Description
PROVISIONING_STATUS_UNSPECIFIED
The status is currently unknown.


WAITING
Waiting for provisioning


IN_PROGRESS
Provisioning in progress


FAILED
Provisioning failed. See provisioning error descriptions


 
trunkId
string
The trunk ID if the type is EST. The trunkId can be found in your Sinch Customer Dashboard.


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


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


 
capability
Array of strings (Capability) 
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.


 
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
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 (Scheduled Provisioning) 
Represents the ongoing or failed scheduled provisioning job. This field will be empty if the number was both successfully provisioned to the SMS platform and linked to the 10DLC campaign.


 
servicePlanId
string
The SMS service plan that the scheduled provisioning job will configure with the number.


 
campaignId
string
TCR campaign ID that the scheduled provisioning job will configure with the number.


 
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]<(https://developers.sinch.com/docs/numbers/api-reference/error-codes/provisioning-errors) and troubleshooting recommendations.


 Enum Value Description
PROVISIONING_STATUS_UNSPECIFIED
The status is currently unknown.


WAITING
Waiting for provisioning


IN_PROGRESS
Provisioning in progress


FAILED
Provisioning failed. See provisioning error descriptions


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


 
errorCodes
Array of strings (SMS Error Code) 
Items Enum Value Description
ERROR_CODE_UNSPECIFIED
Code not specified.


INTERNAL_ERROR
Internal server error.


SMS_PROVISIONING_FAILED
Provisioning for SMS failed.


CAMPAIGN_PROVISIONING_FAILED
Provisioning for campaign failed.


CAMPAIGN_NOT_AVAILABLE
The specified campaign is not available.


EXCEEDED_10DLC_LIMIT
Exceeded the 10DLC limit.


NUMBER_PROVISIONING_FAILED
Failed to provision the number.


PARTNER_SERVICE_UNAVAILABLE
The third party service is unavailable.


CAMPAIGN_PENDING_ACCEPTANCE
The campaign is awaiting acceptance.


MNO_SHARING_ERROR
Sharing error.


CAMPAIGN_EXPIRED
The specific campaign has expired.


CAMPAIGN_MNO_REJECTED
The MNO for the campaign was rejected.


CAMPAIGN_MNO_SUSPENDED
The MNO for the campaign was suspended.


CAMPAIGN_MNO_REVIEW
The MNO for the campaign is under review.


INSUFFICIENT_BALANCE
The credit balance for the account is insufficient to cover the fees.


MOCK_CAMPAIGN_NOT_ALLOWED
Mock campaign is not permitted.


TFN_NOT_ALLOWED
The Toll-Free number is not allowed.


INVALID_NNID
The specified NNID is invalid.


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


 
type
string (VoiceApplicationType) 
 Default:  "RTC"
The voice application type. Examples are RTC, EST, FAX


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


 
object (Scheduled Voice Provisioning) 
Represents the ongoing or failed scheduled voice provisioning job. This field will be empty if the number was successfully provisioned provisioned for voice.


 
type
required
string (VoiceApplicationType) 
 Default:  "RTC"
The voice application type. Examples are RTC, EST, FAX


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


 
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]<(https://developers.sinch.com/docs/numbers/api-reference/error-codes/provisioning-errors) and troubleshooting recommendations.


 Enum Value Description
PROVISIONING_STATUS_UNSPECIFIED
The status is currently unknown.


WAITING
Waiting for provisioning


IN_PROGRESS
Provisioning in progress


FAILED
Provisioning failed. See provisioning error descriptions


 
trunkId
string
The trunk ID if the type is EST. The trunkId can be found in your Sinch Customer Dashboard.


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


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


 
400
400 Invalid Argument error


403
PERMISSION_DENIED: improper credentials. Be sure your projectId, username and password are correct.


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": "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
With this endpoint, you can retrieve the emergency address associated with this 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
streetNumber
string
The street number for the emergency address.


 
streetInfo
string
The street name of the emergency location.


 
location
string
The location for address.


 
city
string
The city of the emergency location.


 
state
string
The state or province of the emergency location.


 
postalCode
string
The postal code of the emergency location.


 
postalCodePlusFour
string
The postal code of the emergency location.


 
400
400 Invalid Argument error


403
PERMISSION_DENIED: improper credentials. Be sure your projectId, username and password are correct.


404
404 Not Found error


500
500 Internal Server error


get/v1/projects/{projectId}/activeNumbers/{phoneNumber}/emergencyAddress
Request samples 
Response samples 
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
With this endpoint, you can provision an emergency address associated with this 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
Request Body schema: application/json
Request to provision an emergency address for a number.


displayName
required
string
Name for emergency address.


 
required
object (Emergency Address) 
Details of the emergency address.


 
streetNumber
required
string
The street number for the emergency address.


 
streetInfo
required
string
The street name of the emergency location.


 
city
required
string
The city of the emergency location.


 
state
required
string
The state or province of the emergency location.


 
postalCode
required
string
The postal code of the emergency location.


 
location
string
The location for address.


 
postalCodePlusFour
string
The postal code of the emergency location.


 
Responses 
200
A successful response, or an error


Response Schema: application/json
streetNumber
string
The street number for the emergency address.


 
streetInfo
string
The street name of the emergency location.


 
location
string
The location for address.


 
city
string
The city of the emergency location.


 
state
string
The state or province of the emergency location.


 
postalCode
string
The postal code of the emergency location.


 
postalCodePlusFour
string
The postal code of the emergency location.


 
400
400 Invalid Argument error


403
PERMISSION_DENIED: improper credentials. Be sure your projectId, username and password are correct.


404
404 Not Found error


500
500 Internal Server error


post/v1/projects/{projectId}/activeNumbers/{phoneNumber}/emergencyAddress:provision
Request samples 
application/json
{
  • "displayName": "New Emergency Address",
  • "address": {
    • "streetNumber": "12345",
    • "streetInfo": "Main St",
    • "city": "Springfield",
    • "state": "IL",
    • "postalCode": "62701"
    }
}
Response samples 
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.
With this endpoint, you can deprovision the emergency address associated with this 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


400
400 Invalid Argument error


403
PERMISSION_DENIED: improper credentials. Be sure your projectId, username and password are correct.


404
404 Not Found error


500
500 Internal Server error


post/v1/projects/{projectId}/activeNumbers/{phoneNumber}/emergencyAddress:deprovision
Request samples 
Response samples 
application/json
{
  • "error": {
    • "code": 400,
    • "message": "string",
    • "status": "INVALID_ARGUMENT",
    • "details": [
      ]
    }
}
Validate the emergency address for a number.
With this endpoint, you can validate the emergency address associated with this 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
Request Body schema: application/json
Request to validate an emergency address for a number.


displayName
required
string
Name for emergency address.


 
required
object (Emergency Address) 
Details of the emergency address.


 
streetNumber
required
string
The street number for the emergency address.


 
streetInfo
required
string
The street name of the emergency location.


 
city
required
string
The city of the emergency location.


 
state
required
string
The state or province of the emergency location.


 
postalCode
required
string
The postal code of the emergency location.


 
location
string
The location for address.


 
postalCodePlusFour
string
The postal code of the emergency location.


 
Responses 
200
A successful response, or an error


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


 
displayName
string
User supplied name for the phone number.


 
object (Emergency Address) 
Details of the emergency address.


 
streetNumber
string
The street number for the emergency address.


 
streetInfo
string
The street name of the emergency location.


 
location
string
The location for address.


 
city
string
The city of the emergency location.


 
state
string
The state or province of the emergency location.


 
postalCode
string
The postal code of the emergency location.


 
postalCodePlusFour
string
The postal code of the emergency location.


 
validationResult
string (AddressValidationResultCode) 
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


 
validationMessage
string
Validation result message


 
object (Emergency Address) 
Details of the emergency address.


 
streetNumber
string
The street number for the emergency address.


 
streetInfo
string
The street name of the emergency location.


 
location
string
The location for address.


 
city
string
The city of the emergency location.


 
state
string
The state or province of the emergency location.


 
postalCode
string
The postal code of the emergency location.


 
postalCodePlusFour
string
The postal code of the emergency location.


 
Array of objects (Emergency Address) 
List of candidate addresses (only available if validationResult == NO_MATCH)


 
 Array 
streetNumber
string
The street number for the emergency address.


 
streetInfo
string
The street name of the emergency location.


 
location
string
The location for address.


 
city
string
The city of the emergency location.


 
state
string
The state or province of the emergency location.


 
postalCode
string
The postal code of the emergency location.


 
postalCodePlusFour
string
The postal code of the emergency location.


 
400
400 Invalid Argument error


404
404 Not Found error


500
500 Internal Server error


post/v1/projects/{projectId}/activeNumbers/{phoneNumber}/emergencyAddress:validate
Request samples 
application/json
{
  • "displayName": "New Emergency Address",
  • "address": {
    • "streetNumber": "12345",
    • "streetInfo": "Main St",
    • "city": "Springfield",
    • "state": "IL",
    • "postalCode": "62701"
    }
}
Response samples 
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": [ ]
}
SecurityPrivacyLegal & ComplianceCookie Statement
© 2025 Sinch. All rights reserved.