Exotel Developer Portal

Whitelist API allows you to add your DND clients' phone numbers into the Exotel's system and hence allowing you to call them. Exotel maintains the list of phone numbers subscribed to TRAI regulated DND (Do Not Disturb) / NCPR (National Customer Preference Registry). In general, a phone number subscribed to DND should not be dialed for marketing/commercial calls. Exotel differentiates these as transactional calls and promotional calls.

This whitelisting is valid only for the next 6 months, post which you will have to ask your customer again if they wish to be contacted.

This is how it works:

You use the Customer whitelist API and add your DND customers' numbers into the Whitelist
An SMS is automatically sent to these numbers asking them their permission for you to contact them. Sample SMS: You've registered with <Your-company-Name> and permitted us to call you. If this is not the case, please give a missed call to 09XXXXXXXX. Thank you!
You can choose the brand name that goes in the opt-in SMS (<Your-company-Name> in the above Sample SMS). You can edit this in the "Brand Name" field in the company info page
If the person does not want to receive calls from you, s/he can 'unsubscribe' by giving a missed call to a specified number (in a SMS). Following this you will not be able to call him/her.
Once you have 'whitelisted' a DND number, you can make outbound transactional calls to that number

Important: If more than 3 people 'unsubscribe', then the process for whitelisting will change. Now, instead of getting a number that is on DND to 'unsubscribe' by giving a missed call, for you to be able to call him/her, the number will have to 'subscribe' by giving a missed call. Steps 3,4 will change accordingly. The following steps will then take place:

Sample SMS: You've registered with <Your-company-name>. As you're on DND, please authorise us to call you by giving a missed call to 09XXXXXXXXX
If the person wants to receive calls from you, they would have to give a missed call on the given number. Until that, you would be unable to contact that number
This is done to ensure that this whitelist API is used genuinely and only for transactional calls
The above mentioned SMSes are sent from your registered sender ID and the cost of the SMS will be deducted from your account

To use this API, an agreement outlining the clauses pertaining to calling NCPR numbers, needs to be signed and sent across to Exotel. Please contact your account manager for further details.

To start with, a list of DND numbers, who you wish to contact, needs to be prepared. While posting these numbers to Exotel, a Virtual Number/ExoPhone need to be specified using which SMSes can be sent to the DND numbers. On posting to Exotel, a SMS is sent to the DND number informing them that a company has added them as a client and an option is given to accept or deny calls from the company.

Adding to the whitelist

To add a list of DND numbers through our API, you will need to make a HTTP POST request to

POST

https://<your_api_key>:<your_api_token><subdomain>/v1/Accounts/<your_sid>/CustomerWhitelist/

If you’d prefer response in JSON format, just append .json at the end of the HTTP POST request.

Replace <your_api_key> and <your_api_token> with the API key and token created by you.
Replace <your_sid> with your “Account sid”
Replace <subdomain> with the region of your account
1. <subdomain> of Singapore cluster is @api.exotel.com
2. <subdomain> of Mumbai cluster is @api.in.exotel.com

<your_api_key> , <your_api_token> and <your_sid> are available in the API settings page of your Exotel Dashboard

The following are the POST parameters:

Parameter Name	Mandatory/Optional	Value
VirtualNumber	Mandatory	This is your ExoPhone/Virtual Number (pick one from here)
Number	Mandatory	List of phone numbers to be added in the whitelist.
Language	Optional	The Language parameter specifies the language in which the SMS should be sent to the user. The following languages are supported. en - English ta - Tamil The default Language is English (en).

 curl -X POST https://<your_api_key>:<your_api_token><subdomain>/v1/Accounts/<your_sid>/CustomerWhitelist/ \
 -d "VirtualNumber=XXXXX30240" \
 -d "Number=XXXXX40682" \
 -d "Language=en"

var request = require('request');

var dataString = 'VirtualNumber=XXXXX30240&Number=XXXXX40682&Language=en';

var options = {
    url: 'https://<your_api_key>:<your_api_token><subdomain>/v1/Accounts/<your_sid>/CustomerWhitelist/',
    method: 'POST',
    body: dataString
};

function callback(error, response, body) {
    if (!error && response.statusCode == 200) {
        console.log(body);
    }
}

request(options, callback);

<?php
include('vendor/rmccue/requests/library/Requests.php');
Requests::register_autoloader();
$headers = array();
$data = array(
    'VirtualNumber' => 'XXXXX30240',
    'Number' => 'XXXXX40682',
    'Language' => 'en'
);
$response = Requests::post('https://<your_api_key>:<your_api_token><subdomain>/v1/Accounts/<your_sid>/CustomerWhitelist/', $headers, $data);

import requests

data = {
  'VirtualNumber': 'XXXXX30240',
  'Number': 'XXXXX40682',
  'Language': 'en'
}

requests.post('https://<your_api_key>:<your_api_token><subdomain>/v1/Accounts/<your_sid>/CustomerWhitelist/', data=data)

require 'net/http'
require 'uri'

uri = URI.parse("https://<your_api_key>:<your_api_token><subdomain>/v1/Accounts/<your_sid>/CustomerWhitelist")
request = Net::HTTP::Post.new(uri)
request.set_form_data(
  "VirtualNumber" => "XXXXX30240",
  "Number" => "XXXXX40682",
  "Language" => "en",
)

req_options = {
  use_ssl: uri.scheme == "https",
}

response = Net::HTTP.start(uri.hostname, uri.port, req_options) do |http|
  http.request(request)
end

# response.code
# response.body

HTTP Response:

On success, the HTTP response status code will be 200
the HTTP body will contain an XML/JSON similar to the one below

Example Response
XML

<?xml version="1.0" encoding="UTF-8"?>
<TwilioResponse>
<Result>
<Total>2</Total>
<Duplicate>0</Duplicate>
<Processed>2</Processed>
<Succeeded>2</Succeeded>
<Redundant>0</Redundant>
<Failed>0</Failed>
<Message>The numbers have been added to the whitelist. If DND number gives a missed call to unsubscribe, the corresponding number will be removed from whitelist.</Message>
</Result>
</TwilioResponse>

Description of parameters mentioned in the above response:

Parameter Name	Type & Value
Result/Total	Total numbers provided
Result/Duplicate	Count of duplicate numbers skipped
Result/Processed	Count of processed numbers
Result/Succeeded	Count of successfully processed numbers
Result/Redundant	Count of number with no action taken
Result/Failed	Count of failed numbers
Message	Description of the action in plain text. The text 'The numbers have been added to the whitelist' would be present in the message only when Result/Succeeded > 0

Deleting from the whitelist

To delete a list of whitelisted numbers through our API, you will need to make a HTTP DELETE request to

DELETE

https://<your_api_key>:<your_api_token><subdomain>/v1/Accounts/<your_sid>/CustomerWhitelist?Number=94870XXXX,97902XXXX

If you’d prefer response in JSON format, just append .json at the end of the HTTP DELETE request.

Replace <your_api_key> and <your_api_token> with the API key and token created by you. Similarly, replace <your_sid> with your “Account sid” value. These values are available in the API settings page of your Exotel Dashboard.

 curl -X DELETE https://<your_api_key>:<your_api_token><subdomain>/v1/Accounts/<your_sid>/CustomerWhitelist?Number=94870XXXX,97902XXXX

var request = require('request');

var dataString = 'VirtualNumber=XXXXX30240&Number=XXXXX40682&Language=en';

var options = {
    url: 'https://<your_api_key>:<your_api_token><subdomain>/v1/Accounts/<your_sid>/CustomerWhitelist?Number=94870XXXX,97902XXXX',
    method: 'DELETE',
    body: dataString
};

function callback(error, response, body) {
    if (!error && response.statusCode == 200) {
        console.log(body);
    }
}

request(options, callback);

<?php
include('vendor/rmccue/requests/library/Requests.php');
Requests::register_autoloader();
$headers = array();
$data = array(
    'VirtualNumber' => 'XXXXX30240',
    'Number' => 'XXXXX40682',
    'Language' => 'en'
);
$response = Requests::delete('https://<your_api_key>:<your_api_token><subdomain>/v1/Accounts/<your_sid>/CustomerWhitelist?Number=94870XXXX,97902XXXX', $headers, $data);

import requests

data = {
  'VirtualNumber': 'XXXXX30240',
  'Number': 'XXXXX40682',
  'Language': 'en'
}

requests.delete('https://<your_api_key>:<your_api_token><subdomain>/v1/Accounts/<your_sid>/CustomerWhitelist?Number=94870XXXX,97902XXXX', data=data)

require 'net/http'
require 'uri'

uri = URI.parse("https://<your_api_key>:<your_api_token><subdomain>/v1/Accounts/<your_sid>/CustomerWhitelist?Number=94870XXXX,97902XXXX")
request = Net::HTTP::Delete.new(uri)
request.set_form_data(
  "VirtualNumber" => "XXXXX30240",
  "Number" => "XXXXX40682",
  "Language" => "en",
)

req_options = {
  use_ssl: uri.scheme == "https",
}

response = Net::HTTP.start(uri.hostname, uri.port, req_options) do |http|
  http.request(request)
end

# response.code
# response.body

HTTP Response:

On success, the HTTP response status code will be 200
the HTTP body will contain an XML/JSON similar to the one below

Example Response
XML

<?xml version="1.0" encoding="UTF-8"?>
<TwilioResponse>
<Result>
<Total>2</Total>
<Duplicate>0</Duplicate>
<Processed>2</Processed>
<Succeeded>2</Succeeded>
<Redundant>0</Redundant>
<Failed>0</Failed>
<Message>The numbers have been deleted from the whitelist.</Message>
</Result>
</TwilioResponse>

Description of parameters mentioned in the above response:

Parameter Name	Type & Value
Result/Total	Total numbers provided
Result/Duplicate	Count of duplicate numbers skipped
Result/Processed	Count of processed numbers
Result/Succeeded	Count of successfully processed numbers
Result/Redundant	Count of number with no action taken
Result/Failed	Count of failed numbers

Voice

SMS

Exophones

Heartbeat

Call Campaigns

SMS Campaigns

Lead Assist

Users

ExoVerify

Whatsapp

URL shortening

More...

Voice

SMS

Exophones

Heartbeat

Call Campaigns

SMS Campaigns

LeadAssist

More...

Greeting

Connect

Passthru

Transfer

SMS

Email

More

Adding to the whitelist

Deleting from the whitelist