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.

servicePlanId
string

The service_plan_id can be found in the Sinch Customer Dashboard. The service plan ID is what ties your Sinch plan to this particular number.

object (ScheduledProvisioning)
status
any (ProvisioningStatus)

The provisioning status. See a full list of provisioning status descriptions and troubleshooting recommendations.

Enum: "INTERNAL_ERROR" "SMS_PROVISIONING_FAILED" "CAMPAIGN_PROVISIONING_FAILED" "CAMPAIGN_NOT_AVAILABLE" "EXCEEDED_10DLC_LIMIT" "NUMBER_PROVISIONING_FAILED" "PARTNER_SERVICE_UNAVAILABLE" "CAMPAIGN_PENDING_ACCEPTANCE" "MNO_SHARING_ERROR"
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 (VoiceConfiguration)

The current voice configuration for this number.

appId
string

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

object (ScheduledVoiceProvisioning)
status
any (ProvisioningStatus)

The provisioning status. See a full list of provisioning status descriptions and troubleshooting recommendations.

Enum: "INTERNAL_ERROR" "SMS_PROVISIONING_FAILED" "CAMPAIGN_PROVISIONING_FAILED" "CAMPAIGN_NOT_AVAILABLE" "EXCEEDED_10DLC_LIMIT" "NUMBER_PROVISIONING_FAILED" "PARTNER_SERVICE_UNAVAILABLE" "CAMPAIGN_PENDING_ACCEPTANCE" "MNO_SHARING_ERROR"
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)
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.

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

The current SMS configuration for this number.

servicePlanId
string

The service_plan_id can be found in the Sinch Customer Dashboard. The service plan ID is what ties your Sinch plan to this particular number.

object (ScheduledProvisioning)
servicePlanId
string

Service plan of the scheduled provisioning task.

status
any (ProvisioningStatus)

The provisioning status. See a full list of provisioning status descriptions and troubleshooting recommendations.

Enum: "INTERNAL_ERROR" "SMS_PROVISIONING_FAILED" "CAMPAIGN_PROVISIONING_FAILED" "CAMPAIGN_NOT_AVAILABLE" "EXCEEDED_10DLC_LIMIT" "NUMBER_PROVISIONING_FAILED" "PARTNER_SERVICE_UNAVAILABLE" "CAMPAIGN_PENDING_ACCEPTANCE" "MNO_SHARING_ERROR"
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 (VoiceConfiguration)

The current voice configuration for this number.

appId
string

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

object (ScheduledVoiceProvisioning)
appId
string

RTC application ID of the scheduled provisioning task.

status
any (ProvisioningStatus)

The provisioning status. See a full list of provisioning status descriptions and troubleshooting recommendations.

Enum: "INTERNAL_ERROR" "SMS_PROVISIONING_FAILED" "CAMPAIGN_PROVISIONING_FAILED" "CAMPAIGN_NOT_AVAILABLE" "EXCEEDED_10DLC_LIMIT" "NUMBER_PROVISIONING_FAILED" "PARTNER_SERVICE_UNAVAILABLE" "CAMPAIGN_PENDING_ACCEPTANCE" "MNO_SHARING_ERROR"
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",
    • "scheduledProvisioning": {
      },
    • "campaignId": "YOUR_campaignId_from_TCR"
    },
  • "voiceConfiguration": {
    • "appId": "YOUR_Voice_appId",
    • "scheduledProvisioning": {
      }
    }
}
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": "82b42acf74924bd687ef9fb212f2060c",
    • "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. MOBILE, LOCAL or TOLL_FREE.

numberPattern.pattern
string

Sequence of digits to search for.

numberPattern.searchPattern
string

Search pattern to apply.

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)
object (money)
paymentIntervalMonths
integer <int32>

How often the recurring price is charged in months.

supportingDocumentationRequired
boolean

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

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

async function run() {
  const query = new URLSearchParams({
    regionCode: 'US',
    type: 'LOCAL'
  }).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)
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.

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

paymentIntervalMonths
integer <int32>

How often the recurring price is charged in months.

supportingDocumentationRequired
boolean

Whether or not supplementary documentation will be required to complete 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.