Download OpenAPI specification:Download

Available Number

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

Activate a new phone number

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

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

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

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
required

The request to rent a 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
required
string (VoiceApplicationType)

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 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 (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
required
string (VoiceApplicationType)

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
string (VoiceApplicationType)

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 and troubleshooting recommendations.

Enum: "WAITING" "IN_PROGRESS" "FAILED"
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

post/v1/projects/{projectId}/availableNumbers/{phoneNumber}:rent
Request samples
application/json
{}
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"
    }
}

Rent any number that matches the criteria

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

SecurityBasic or OAuth2.0
Request
path Parameters
projectId
required
string

Found on your Sinch Customer Dashboard. Settings > Projects.

Example: YOUR_projectId
Request Body schema: application/json
required

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

regionCode
required
string

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

type
required
string

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

object (Search Pattern)
pattern
string

Sequence of digits to search for.

searchPattern
string (Search Pattern)

The pattern to apply to searches.

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.

capabilities
Array of strings

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

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
required
string (VoiceApplicationType)

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 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 (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
required
string (VoiceApplicationType)

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
string (VoiceApplicationType)

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 and troubleshooting recommendations.

Enum: "WAITING" "IN_PROGRESS" "FAILED"
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

post/v1/projects/{projectId}/availableNumbers:rentAny
Request samples
application/json
{
  • "regionCode": "US",
  • "type": "LOCAL",
  • "capabilities": [
    • "SMS"
    ],
  • "numberPattern": {
    • "pattern": "+1208",
    • "searchPattern": "START"
    },
  • "smsConfiguration": {
    • "servicePlanId": "YOUR_SMS_servicePlanId",
    • "campaignId": "YOUR_campaignId_from_TCR"
    },
  • "callbackUrl": "https://www.your-callback-server.com/callback"
}
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": {
    • "type": "RTC",
    • "lastUpdatedTime": "2019-08-24T14:15:22Z",
    • "scheduledVoiceProvisioning": {
      },
    • "appId": "string"
    },
  • "callbackUrl": "https://www.your-callback-server.com/callback"
}

Search for available phone numbers

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

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

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.

capabilities
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

size
integer <int32>

Optional. The maximum number of items to return.

Example: size=3
Responses
200

A successful response.

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

List of available phone numbers.

Array
phoneNumber
string

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

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.

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.

supportingDocumentationRequired
boolean

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

400

400 Invalid Argument error

404

404 Not Found error

500

500 Internal Server error

get/v1/projects/{projectId}/availableNumbers
Request samples 
Response samples 
application/json
{
  • "availableNumbers": [
    • {
      }
    ]
}
Search for a specific phone number
This endpoint allows you to enter a specific phone number to check if it's available for use. A 200 response will return the number's capability, setup costs, monthly costs and if supporting documentation is required.


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.


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


 
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.


 
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.


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


 
get/v1/projects/{projectId}/availableNumbers/{phoneNumber}
Request samples 
Response samples 
application/json
{
  • "phoneNumber": "+12025550134",
  • "regionCode": "US",
  • "type": "MOBILE",
  • "capability": [
    • "SMS",
    • "VOICE"
    ],
  • "setupPrice": {
    • "currencyCode": "USD",
    • "amount": "2.00"
    },
  • "monthlyPrice": {
    • "currencyCode": "USD",
    • "amount": "2.00"
    },
  • "paymentIntervalMonths": 0,
  • "supportingDocumentationRequired": true
}
SecurityPrivacyLegal & ComplianceCookie Statement
© 2024 Sinch. All rights reserved.