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 virtual number

Activate a virtual 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.

Request
Security:
Basic
or
oAuth2
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 request to rent a number.

object (smsConfiguration)

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 virtual numbers. This campaign ID relates to 10DLC numbers. 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 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.

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 (NumberType)

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 (scheduledProvisioning)

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 (ProvisioningStatus)

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 virtual numbers. This campaign ID relates to 10DLC numbers. So, it is the current campaign ID for this number. The campaign_id 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 (scheduledVoiceProvisioning)

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 (ProvisioningStatus)

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.

post/v1/projects/{projectId}/availableNumbers/{phoneNumber}:rent
Request samples
application/json
{
  • "smsConfiguration": {
    • "servicePlanId": "YOUR_SMS_servicePlanId"
    },
  • "voiceConfiguration": {
    • "appId": "YOUR_Voice_appId"
    }
}
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"
    }
}

Search for virtual numbers

Search for virtual 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.

Request
Security:
Basic
or
oAuth2
path Parameters
projectId
required
string

Found on your Sinch Customer Dashboard. Settings > Projects.

Example: YOUR_projectId
query Parameters
regionCode
required
string
Default: "US"

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

type
required
string
Default: "LOCAL"

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.

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

CONTAIN

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: 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: description=Available numbers schema base.&type=object&properties=[object Object]
Responses
200

A successful response, or an error

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 (NumberType)

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.

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.

get/v1/projects/{projectId}/availableNumbers
Request samples
import fetch from 'node-fetch';

async function run() {
  const query = new URLSearchParams({
    regionCode: 'US',
    type: 'MOBILE'
  }).toString();

  const projectId = 'YOUR_projectId_PARAMETER';
  const resp = await fetch(
    `https://numbers.api.sinch.com/v1/projects/${projectId}/availableNumbers?${query}`,
    {
      method: 'GET',
      headers: {
        Authorization: 'Basic ' + Buffer.from('<username>:<password>').toString('base64')
      }
    }
  );

  const data = await resp.text();
  console.log(data);
}

run();
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.

Request
Security:
Basic
or
oAuth2
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.

regionCode
string

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

type
string (NumberType)

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.

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
import fetch from 'node-fetch';

async function run() {
  const projectId = 'YOUR_projectId_PARAMETER';
  const phoneNumber = 'YOUR_phoneNumber_PARAMETER';
  const resp = await fetch(
    `https://numbers.api.sinch.com/v1/projects/${projectId}/availableNumbers/${phoneNumber}`,
    {
      method: 'GET',
      headers: {
        Authorization: 'Basic ' + Buffer.from('<username>:<password>').toString('base64')
      }
    }
  );

  const data = await resp.text();
  console.log(data);
}

run();
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
© 2022 Sinch. All rights reserved.