Download OpenAPI specification:Download

Active Number

You can use the Active Number API to manage numbers you own. You can assign numbers to projects, release numbers from projects, or list all numbers assigned to a project.

Lists virtual numbers for a project

Lists all virtual numbers for a project.

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.

capability
Array of strings

Number capabilities to filter by SMS and/or VOICE.

Items Enum: Description
SMS

The SMS product can use the number.

VOICE

The Voice product can use the number.

pageSize
integer <int32>

The maximum number of items to return.

pageToken
string

The next_page_token value returned from a previous List request, if any.

orderBy
string

Supported fields for ordering by phoneNumber or displayName.

Responses
200

A successful response, 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 (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)
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.

object (VoiceConfiguration)

The current voice configuration for this number.

nextPageToken
string (The token to be used for listing the next page.)
totalSize
integer <int32> (The maximum number of results returned.)
get/v1/projects/{projectId}/activeNumbers
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}/activeNumbers?${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
{
  • "activeNumbers": [
    • {
      }
    ],
  • "nextPageToken": "string",
  • "totalSize": 0
}

Update a virtual phone number

Update a virtual phone number. For example: you can move a number between different SMS services and give it a new, friendly name. To update the name that displays for a customer, modify the displayName parameter.

You'll use smsConfiguration to update your SMS number and voiceConfiguration to update Voice. To update for both, add both objects. Within these objects, you can update the service plan ID, campaign ID, and scheduled provisioning status. You can also update the type of number, currency type and amount. Note: You cannot add both objects if you only need to update one object. For example, if you only need to reconfigure 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 number body to be updated.

displayName
string

User supplied name for the phone number.

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.

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

patch/v1/projects/{projectId}/activeNumbers/{phoneNumber}
Request samples
application/json
{
  • "displayName": "MyPhoneNumber",
  • "type": "MOBILE",
  • "money": {
    • "currencyCode": "USD",
    • "amount": "2.00"
    },
  • "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"
    }
}

Get a virtual number

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.

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.

get/v1/projects/{projectId}/activeNumbers/{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}/activeNumbers/${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",
  • "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"
    }
}

Release a virtual number from the project

With this endpoint, you can cancel your subscription for a specific virtual phone number.

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.

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}/activeNumbers/{phoneNumber}:release
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}/activeNumbers/${phoneNumber}:release`,
    {
      method: 'POST',
      headers: {
        Authorization: 'Basic ' + Buffer.from('<username>:<password>').toString('base64')
      }
    }
  );

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

run();
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"
    }
}
SecurityPrivacyLegal & ComplianceCookie Statement
© 2022 Sinch. All rights reserved.