Create Lists

This API allows you to create one or more new lists. A list name has to be unique within an account.

The Lists created using this API can only be used within Call Campaigns.

POST

https://<your_api_key>:<your_api_token><subdomain>/v2/accounts/<your_sid>/lists

  • 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

name

Mandatory 

Name of list (unique within an account)

tag

optional 

Tag value for the list

curl -X POST 'https://<your_api_key>:<your_api_token>@<subdomain>/v2/accounts/exotel8u3/lists' \
--header 'Content-Type: application/json' \
--data-raw '{
    "lists": [
        {
        "name": "new-csv_list2"
        }
    ]
}'
var unirest = require('unirest');
var accountSid = "XXXXXXXXX";
var accountToken = "YYYYYYYYY";
var authKey = "ZZZZZZZZZZ";

var encoding = Buffer.from(authKey + ':' + accountToken).toString('base64');
var req = unirest('POST', "https://<subdomain>/v2/accounts/"+accountSid+"/lists")
  .headers({
	  Authorization: 'Basic ' + encoding,
	  'Content-Type': 'application/json'
  })
  .send(JSON.stringify({"lists":[
    {
    	"name":"list123"
    },
		{
			"name":"list345"	
		}
	]}))
  .end(function (res) { 
    if (res.error) throw new Error(res.error); 
    console.log(res.raw_body);
  });
<?php

$curl = curl_init();
$accountSid = "XXXXXXXXXX";
$accountToken = "YYYYYYYYYY";
$authKey = "ZZZZZZZZZZ";

$encoding = base64_encode($authKey .":". $accountToken);

curl_setopt_array($curl, array(
  CURLOPT_URL => 'https://<subdomain>/v2/accounts/exotel8u3/lists',
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => '',
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 0,
  CURLOPT_FOLLOWLOCATION => true,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => 'POST',
  CURLOPT_POSTFIELDS =>'{
    "lists": [
        {
            "name": "list123"
        },
        {
            "name": "list345"
        }
    ]
}',
  CURLOPT_HTTPHEADER => array(
    "Authorization: Basic ".$encoding,
    'Content-Type: application/json'
  ),
));

$response = curl_exec($curl);

curl_close($curl);
echo $response;
import requests
import base64 
import json
accountSid = "XXXXXXXXX"
authToken = "YYYYYYYYY"
authKey = "ZZZZZZZZZZ"

encoding = base64.b64encode(authKey + ":" + authToken)

url = "https://<subdomain>/v2/accounts/"+ accountSid+"/lists"

payload = json.dumps({
    "lists": [
        {
            "name": "list123",
            
        },
        {
            "name": "list345",
            
        }
    ]
})

headers = {
    'Authorization': "Basic " + encoding,
    'Content-Type': 'application/json'
}


response = requests.request("POST", url, data=payload, headers=headers)

print(response.text)
print(json.dumps(json.loads(response.text), indent = 4, sort_keys = True))
package main

import (
	b64 "encoding/base64"
	"fmt"
	"io/ioutil"
	"net/http"
	"strings"
)

func main() {
	// Please provide accountSid, authToken from your Exotel account
	accountSid := "XXXXXXXXX"
	authToken := "YYYYYYYY"
	authKey := "ZZZZZZZZZZ"

	// Encoding the accountSid and authToken, used in Authorization header
	encoding := b64.StdEncoding.EncodeToString([]byte(authKey + ":" + authToken))

	url := "https://<subdomain>/v2/accounts/" + accountSid + "/lists"
	method := "POST"

	payload := strings.NewReader(`{
    "lists": [
        {
        "name": "list31@3"
        }
    ]
}`)

	client := &http.Client{}
	req, err := http.NewRequest(method, url, payload)

	if err != nil {
		fmt.Println(err)
		return
	}
	req.Header.Add("Content-Type", "application/json")
	req.Header.Add("Authorization", "Basic "+encoding)
	res, err := client.Do(req)
	if err != nil {
		fmt.Println(err)
		return
	}
	defer res.Body.Close()

	body, err := ioutil.ReadAll(res.Body)
	if err != nil {
		fmt.Println(err)
		return
	}
	fmt.Println(string(body))
}
{
    "request_id": "b45f202e1ec14b37bc459235a65f8712",
    "method": "POST",
    "http_code": 207,
    "metadata": {
        "failed": 0,
        "total": 1,
        "success": 1
    },
    "response": [
        {
            "code": 200,
            "error_data": null,
            "status": "success",
            "data": {
                "sid": "46cd9106113f4920be56811382ebefba",
                "date_created": "2021-05-23T14:09:32.143446635+05:30",
                "date_updated": "2021-05-23T14:09:32.143446635+05:30",
                "account_sid": "exotel8u3",
                "name": "new-csv_list2",
                "uri": "/v2/accounts/exotel8u3/lists/46cd9106113f4920be56811382ebefba",
                "tag": null,
                "contact_count": null
            }
        }
    ]
}

Add Contacts to a List

This API allows you to add contacts within an already created list. The contacts should already exists in Campaigns or should be created using Create Contacts API.

This is a bulk API which supports maximum of 5000 contacts in one request.

POST

https://<your_api_key>:<your_api_token><subdomain>/v2/accounts/<your_sid>/lists/<listSid>/contacts

  • 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

curl -X POST 'https://<your_api_key>:<your_api_token>@<subdomain>/v2/accounts/exotel8u3/lists/<list_id>/contacts' \
--header 'Content-Type: application/json' \
--data-raw '{
  "contact_references": [
    {"contact_sid":"d49b7a4781ea45dcb702825ce30494ba"},
    {"contact_sid":"68bc98cae5a24cc3b017258a73e8a809"}
  ]
}'
var unirest = require('unirest');
var accountSid = "XXXXXXXXX";
var accountToken = "YYYYYYYYY";
var authKey = "ZZZZZZZZZZ";
var encoding = Buffer.from(authKey + ':' + accountToken).toString('base64');
var req = unirest('POST', "https://<subdomain>/v2/accounts/"+accountSid+"/lists/+list_id+/contacts")
  .headers({
	  Authorization: 'Basic ' + encoding,
	  'Content-Type': 'application/json'
  })
  .send(JSON.stringify({"{   "contact_references": [     {"contact_sid":"d49b7a4781ea45dcb702825ce30494ba"},     {"contact_sid":"68bc98cae5a24cc3b017258a73e8a809"}   ] }"
))
  .end(function (res) { 
    if (res.error) throw new Error(res.error); 
    console.log(res.raw_body);
  });
<?php

$curl = curl_init();
$accountSid = "XXXXXXXXXX";
$accountToken = "YYYYYYYYYY";
$authKey = "ZZZZZZZZZZ";

$encoding = base64_encode($authKey .":". $accountToken);

curl_setopt_array($curl, array(
  CURLOPT_URL => 'https://<subdomain>/v2/accounts/<account_sid>/lists/<list_id>/contacts',
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => '',
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 0,
  CURLOPT_FOLLOWLOCATION => true,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => 'POST',
  CURLOPT_POSTFIELDS =>'{   "contact_references": [     {"contact_sid":"d49b7a4781ea45dcb702825ce30494ba"},     {"contact_sid":"68bc98cae5a24cc3b017258a73e8a809"}   ] }',
  CURLOPT_HTTPHEADER => array(
    "Authorization: Basic ".$encoding,
    'Content-Type: application/json'
  ),
));

$response = curl_exec($curl);

curl_close($curl);
echo $response;
import requests
import base64 
import json
accountSid = "XXXXXXXXX"
authToken = "YYYYYYYYY"
authKey = "ZZZZZZZZZZ"

encoding = base64.b64encode(authKey + ":" + authToken)

url = "https://<subdomain>/v2/accounts/"+accountSid+"/lists/+list_id+/contacts"

payload = json.dumps({   "contact_references": [     {"contact_sid":"d49b7a4781ea45dcb702825ce30494ba"},     {"contact_sid":"68bc98cae5a24cc3b017258a73e8a809"}   ] })

headers = {
    'Authorization': "Basic " + encoding,
    'Content-Type': 'application/json'
}


response = requests.request("POST", url, data=payload, headers=headers)
print(response.text)
print(json.dumps(json.loads(response.text), indent = 4, sort_keys = True))
package main

import (
	b64 "encoding/base64"
"fmt"
"io/ioutil"
"net/http"
"strings"
)

func main() {
// Please provide accountSid, authToken from your Exotel account
	accountSid := "XXXXXXXXX"
	authToken := "YYYYYYYY"
	authKey := "ZZZZZZZZZZ"
// Encoding the accountSid and authToken, used in Authorization header
	encoding := b64.StdEncoding.EncodeToString([]byte(authKey + ":" + authToken))

	url := "https://<subdomain>/v2/accounts/" + accountSid + "/lists" + list_id + "/contacts"
	method := "POST"

	payload := strings.NewReader(`{   "contact_references": [     {"contact_sid":"d49b7a4781ea45dcb702825ce30494ba"},     {"contact_sid":"68bc98cae5a24cc3b017258a73e8a809"}   ] }`)

	client := &http.Client{}
	req, err := http.NewRequest(method, url, payload)
if err != nil {
		fmt.Println(err)
return
}
	req.Header.Add("Content-Type", "application/json")
	req.Header.Add("Authorization", "Basic "+encoding)
	res, err := client.Do(req)
if err != nil {
		fmt.Println(err)
return
}
	defer res.Body.Close()

	body, err := ioutil.ReadAll(res.Body)
if err != nil {
		fmt.Println(err)
return
}
	fmt.Println(string(body))
}
{
  "request_id":"cfa7d61f24064a399789d677ef0cc379",
  "method":"POST",
  "http_code":207,
  "metadata":{
     "failed":0,
     "total":1,
     "success":1
  },
  "response":[
     {
       "code":200,
       "error_data":null,
       "status":"success",
       "data":{
       "sid":"d49b7a4781ea45dcb702825ce30494ba",
       "date_created":"2017-12-05T14:15:51.108069088+05:30",
       "date_updated":"2017-12-05T14:15:51.108069088+05:30",
       "account_sid":"Exotel",
       "list_id":"e46c2fe202904d579ae592d108cf87a0",
       "uri":"/v2/Accounts/Exotel/contacts/d49b7a4781ea45dcb702825ce30494ba"
   },
    {
      "Sid":"68bc98cae5a24cc3b017258a73e8a809",
      "date_created":"2017-12-05T14:15:51.108069088+05:30",
      "date_updated":"2017-12-05T14:15:51.108069088+05:30",
      "account_sid":"Exotel", "list_id":"e46c2fe202904d579ae592d108cf87a0",
      "uri":"/v2/Accounts/Exotel/contacts/68bc98cae5a24cc3b017258a73e8a809"
   }
  }
  ]
}

Add Contacts to a List via CSV

This API allows you to add new contacts in a list using a CSV. The CSV must be present in local to the client triggering the API. The API uploads the contacts in asynchronous manner. The status of upload, at any point of time, can be fetched by hitting the URL (present in summary section of the API response). 

Maximum of 1 Lakh contacts can be added in a list using this API. If the list already exists and has contacts, then it can allow addition of new contacts only up till maximum of 1 Lakh. 

CSV should contain 'number' (in E.164 format) as a mandatory column, while other optional columns are: first_name, last_name, company_name, email & tag. Custom field is not allowed to be added against contacts, in this method. The contact parameters can be referred from the API 'Create Contacts'.

Sample_CSV_Contacts_Upload

POST

https://<your_api_key>:<your_api_token><subdomain>/v2/accounts/<your_sid>/contacts/csv-upload

  • 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
list_name Mandatory

The list name in which the new contacts will be added

filepath Mandatory The local path of the file which will be used to upload the contacts.
curl -X POST 'https://<your_api_key>:<your_api_token>@<subdomain>/v2/accounts/exotel/contacts/csv-upload' \
--header 'Content-Type: multipart/form-data' \
--data-raw '{
  "list_name":"xyz",
  "filepath":"path/of/csv-file"
}'
var unirest = require('unirest');
var accountSid = "XXXXXXXXX";
var accountToken = "YYYYYYYYY";
var authKey = "ZZZZZZZZZZ";
var encoding = Buffer.from(authKey + ':' + accountToken).toString('base64');
var req = unirest('POST', "https://<subdomain>/v2/accounts/exotel/contacts/csv-upload")
  .headers({
	  Authorization: 'Basic ' + encoding,
	  'Content-Type': 'multipart/form-data'
  })
  .send(JSON.stringify({"list_name":"xyz",
  "filepath":"path/of/csv-file"}
))
  .end(function (res) { 
    if (res.error) throw new Error(res.error); 
    console.log(res.raw_body);
  });
<?php

$curl = curl_init();
$accountSid = "XXXXXXXXXX";
$accountToken = "YYYYYYYYYY";
$authKey = "ZZZZZZZZZZ";

$encoding = base64_encode($authKey .":". $accountToken);

curl_setopt_array($curl, array(
  CURLOPT_URL => 'https://<subdomain>/v2/accounts/exotel/contacts/csv-upload',
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => '',
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 0,
  CURLOPT_FOLLOWLOCATION => true,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => 'POST',
  CURLOPT_POSTFIELDS =>'{ "list_name":"xyz",
  "filepath":"path/of/csv-file" }',
  CURLOPT_HTTPHEADER => array(
    "Authorization: Basic ".$encoding,
    'Content-Type: multipart/form-data'
  ),
));

$response = curl_exec($curl);

curl_close($curl);
echo $response;
import requests
import base64 
import json
accountSid = "XXXXXXXXX"
authToken = "YYYYYYYYY"
authKey = "ZZZZZZZZZZ"

encoding = base64.b64encode(authKey + ":" + authToken)

url = "https://<subdomain>/v2/accounts/exotel/contacts/csv-upload"

payload = json.dumps({ "list_name":"xyz",
  "filepath":"path/of/csv-file" })

headers = {
    'Authorization': "Basic " + encoding,
    'Content-Type': 'multipart/form-data'
}


response = requests.request("POST", url, data=payload, headers=headers)
print(response.text)
print(json.dumps(json.loads(response.text), indent = 4, sort_keys = True))
package main

import (
	b64 "encoding/base64"
"fmt"
"io/ioutil"
"net/http"
"strings"
)

func main() {
// Please provide accountSid, authToken from your Exotel account
	accountSid := "XXXXXXXXX"
	authToken := "YYYYYYYY"
	authKey := "ZZZZZZZZZZ"
// Encoding the accountSid and authToken, used in Authorization header
	encoding := b64.StdEncoding.EncodeToString([]byte(authKey + ":" + authToken))

	url := "https://<subdomain>/v2/accounts/exotel/contacts/csv-upload"
	method := "POST"

	payload := strings.NewReader(`{  "list_name":"xyz",
  "filepath":"path/of/csv-file" }`)

	client := &http.Client{}
	req, err := http.NewRequest(method, url, payload)
if err != nil {
		fmt.Println(err)
return
}
	req.Header.Add("Content-Type", "multipart/form-data")
	req.Header.Add("Authorization", "Basic "+encoding)
	res, err := client.Do(req)
if err != nil {
		fmt.Println(err)
return
}
	defer res.Body.Close()

	body, err := ioutil.ReadAll(res.Body)
if err != nil {
		fmt.Println(err)
return
}
	fmt.Println(string(body))
}

The following are the response parameters:

Parameter Name   Mandatory/Optional Value

request_id

Mandatory 

Random unique UUID to identify the request

method

Mandatory 

HTTP method (post/delete/get/put)

http_code

Mandatory 

HTTP Code of the response

list: sid

Mandatory 

Unique uuid of the list

list: name

Mandatory 

Name of the list

list: uri

Mandatory 

Unique URL of the list

list: tag

Mandatory 

Tag of the list

list: contact_count

Mandatory 

Total number of contacts in the list

summary: list_sid

Mandatory

Unique UUID of list

summary: upload_id

Mandatory

Unique id for identify the csv file which got uploaded

summary: url

Mandatory

Csv-check url to check contacts stats. This URL can be used as GET API to fetch the live status of CSV upload. Refer section 'CSV Upload Status' below

summary: stats

Mandatory

total:  Total contacts in csv file

duplicate: duplicate contacts in file

Invalid: invalid contacts in file

success:  successfully created new contacts

{
   "request_id": "256c7bb3b18d477a8f11089841841092",
   "method": "POST",
   "http_code": 200,
   "response": {
       "code": 200,
       "error_data": null,
       "status": "success",
       "data": {
           "list": {
               "sid": "f121e1f304654a668108127a1412b0fb",
               "date_created": "2021-06-03T16:42:26.522002459+05:30",
               "date_updated": "2021-06-03T16:42:26.522002459+05:30",
               "account_sid": "exotel",
               "name": "csv_list124",
               "uri": "/v2/accounts/exotel/lists/f121e1f304654a668108127a1412b0fb",
               "tag": null,
               "contact_count": 0
           },
           "summary": {
               "upload_id": "b3eb726b829c432cb3dae4e9f9dda913",
               "list_sid": "f121e1f304654a668108127a1412b0fb",
               "url": "/v2/accounts/exotel/csv-status/b3eb726b829c432cb3dae4e9f9dda913",
               "accountSid": "exotel",
               "date_created": "2021-06-03T16:42:26.524066171+05:30",
               "date_updated": "2021-06-03T16:42:26.524066171+05:30",
               "status": "in-progress",
               "Stats": {
                   "duplicate": null,
                   "total": null,
                   "success": null,
                   "failed": null
               }
           }
       }
   }

 

CSV Upload Status

The status of CSV upload can be checked in real-time using the 'summary:url' in the above response as a GET API. The response of this request will show the overall status and stats of contacts being uploaded.

GET

https://<your_api_key>:<your_api_token><subdomain>/v2/accounts/<your_sid>/csv-status/<upload_id>

curl -XGET 'https://<your_api_key>:<your_api_token>@<subdomain>/v2/accounts/exotel/lists/f121e1f304654a668108127a1412b0fb'
{
   "request_id": "f5858bb48c0a465a83b02eff24a4dd08",
   "method": "GET",
   "http_code": 200,
   "response": {
       "code": 200,
       "error_data": null,
       "status": "success",
       "data": {
           "upload_id": "b3eb726b829c432cb3dae4e9f9dda913",
           "list_sid": "f121e1f304654a668108127a1412b0fb",
           "url": "/v2/accounts/exotel8u3/csv-status/b3eb726b829c432cb3dae4e9f9dda913",
           "accountSid": "exotel8u3",
           "date_created": "2021-06-03T11:12:27Z",
           "date_updated": "2021-06-03T16:42:28Z",
           "status": "completed",
           "stats": {
               "duplicate": 0,
               "total": 6,
               "success": 5,
               "failed": 1
           }
       }
   }
}

Update a List

This API allows you to update the name or tag of a list.

PUT

https://<your_api_key>:<your_api_token><subdomain>/v2/accounts/<your_sid>/lists/<listSid>

  • 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

curl -X PUT 'https://<your_api_key>:<your_api_token>@<subdomain>/v2/accounts/<account_sid>/lists/<list_sid>' \
--header 'Content-Type: application/json' \
--data-raw '{
        "name": "listXYZ"
}'
var unirest = require('unirest');
var unirest = require('unirest');
var accountSid = "XXXXXXXXX";
var accountToken = "YYYYYYYYY";
var authKey = "ZZZZZZZZZZ";

var encoding = Buffer.from(authKey + ':' + accountToken).toString('base64');
var req = unirest('PUT', 'https://<subdomain>/v2/accounts/exotel8u3/lists/<list_sid>')
  .headers({
      Authorization: 'Basic ' + encoding,
      'Content-Type': 'application/json'
  })
  .send(JSON.stringify({"name":"XYZ"})
  .end(function (res) { 
    if (res.error) throw new Error(res.error); 
    console.log(res.raw_body);
  });
<?php

$curl = curl_init();
$accountSid = "XXXXXXXXXX";
$accountToken = "YYYYYYYYYY";
$authKey = "ZZZZZZZZZZ";

$encoding = base64_encode($authKey .":". $accountToken);
$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => 'https://<subdomain>/v2/accounts/exotel8u3/lists/<list_sid>',
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => '',
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 0,
  CURLOPT_FOLLOWLOCATION => true,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => 'PUT',
  CURLOPT_POSTFIELDS =>'{
            "name": "listXYZ"
}',
  CURLOPT_HTTPHEADER => array(
    'Content-Type: application/json',
    "Authorization: Basic ".$encoding
  ),
));

$response = curl_exec($curl);

curl_close($curl);
echo $response;
import requests
import base64 
import json
accountSid = "XXXXXXXXX"
authToken = "YYYYYYYYY"
authKey = "ZZZZZZZZZZ"

encoding = base64.b64encode(authKey + ":" + authToken)

url = "https://<subdomain>/v2/accounts/exotel8u3/lists/<list_sid>"

payload = json.dumps({
            "name": "listXYZ"
})
headers = {
  'Content-Type': 'application/json',
  'Authorization': "Basic " + encoding
}

response = requests.request("PUT", url, headers=headers, data=payload)

print(response.text)
package main

import (
	b64 "encoding/base64"
	"fmt"
	"io/ioutil"
	"net/http"
	"strings"
)

func main() {
	// Please provide accountSid, authToken from your Exotel account
	accountSid := "XXXXXXXXX"
	authToken := "YYYYYYYY"
	authKey := "ZZZZZZZZZZ"

	// Encoding the accountSid and authToken, used in Authorization header
	encoding := b64.StdEncoding.EncodeToString([]byte(authKey + ":" + authToken))

	url := "https://<subdomain>/v2/accounts/" + accountSid + "/lists/<list_sid>"
	method := "PUT"

	payload := strings.NewReader(`{
			  "name": "list_123"
  }`)

	client := &http.Client{}
	req, err := http.NewRequest(method, url, payload)

	if err != nil {
		fmt.Println(err)
		return
	}
	req.Header.Add("Content-Type", "application/json")
	req.Header.Add("Authorization", "Basic "+encoding)

	res, err := client.Do(req)
	if err != nil {
		fmt.Println(err)
		return
	}
	defer res.Body.Close()

	body, err := ioutil.ReadAll(res.Body)
	if err != nil {
		fmt.Println(err)
		return
	}
	fmt.Println(string(body))
}
{
    "request_id": "b45f202e1ec14b37bc459235a65f8712",
    "method": "POST",
    "http_code": 207,
    "metadata": {
        "failed": 0,
        "total": 1,
        "success": 1
    },
    "response": {
            "code": 200,
            "error_data": null,
            "status": "success",
            "data": {
                "sid": "46cd9106113f4920be56811382ebefba",
                "date_created": "2021-05-23T14:09:32.143446635+05:30",
                "date_updated": "2021-05-23T14:09:32.143446635+05:30",
                "account_sid": "exotel8u3",
                "name": "listXYZ",
                "uri": "/v2/accounts/exotel8u3/lists/46cd9106113f4920be56811382ebefba",
                "tag": null,
                "contact_count": null
            }
        }
}

Bulk Lists Update

This API allows you update name and tag of multiple lists.

It's a bulk API and which supports 5000 lists in one request.

PUT

https://<your_api_key>:<your_api_token><subdomain>/v2/accounts/<your_sid>/lists

  • 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

curl -X PUT 'https://<your_api_key>:<your_api_token>@<subdomain>/v2/accounts/<account_sid>/lists' \
--header 'Content-Type: application/json' \
--data-raw '{
    "lists": [
        { 
           "sid": "d49b7a4781ea45dcb702825ce30494ba", 
           "name": "list_123" },
        {
           "sid": "e59b7a4781ea45dcb702825ce30495cd", 
           "name": "list_456" 
        }
    ]
}'
var unirest = require('unirest');
var unirest = require('unirest');
var accountSid = "XXXXXXXXX";
var accountToken = "YYYYYYYYY";
var authKey = "ZZZZZZZZZZ";

var encoding = Buffer.from(authKey + ':' + accountToken).toString('base64');
var req = unirest('PUT', 'https://<subdomain>/v2/accounts/<account_sid>/lists')
  .headers({
      Authorization: 'Basic ' + encoding,
      'Content-Type': 'application/json'
  })
  .send(JSON.stringify({ "lists": [{ 
"sid": "d49b7a4781ea45dcb702825ce30494ba", 
"name": "list_123" }
{
"sid": "e59b7a4781ea45dcb702825ce30495cd", 
"name": "list_456" 
}]}))
  .end(function (res) { 
    if (res.error) throw new Error(res.error); 
    console.log(res.raw_body);
  });
<?php

$curl = curl_init();
$accountSid = "XXXXXXXXXX";
$accountToken = "YYYYYYYYYY";
$authKey = "ZZZZZZZZZZ";

$encoding = base64_encode($authKey .":". $accountToken);
$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => 'https://<subdomain>/v2/accounts/exotel8u3/lists',
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => '',
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 0,
  CURLOPT_FOLLOWLOCATION => true,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => 'PUT',
  CURLOPT_POSTFIELDS =>'{
    "lists": [
        { 
            "sid": "d49b7a4781ea45dcb702825ce30494ba", 
            "name": "list_123" }
        {
            "sid": "e59b7a4781ea45dcb702825ce30495cd", 
            "name": "list_456" 
         }
    ]
}',
  CURLOPT_HTTPHEADER => array(
    'Content-Type: application/json',
    "Authorization: Basic ".$encoding
  ),
));

$response = curl_exec($curl);

curl_close($curl);
echo $response;
import requests
import base64 
import json
accountSid = "XXXXXXXXX"
authToken = "YYYYYYYYY"
authKey = "ZZZZZZZZZZ"

encoding = base64.b64encode(authKey + ":" + authToken)

url = "https://<subdomain>/v2/accounts/exotel8u3/lists"

payload = json.dumps({"lists": [
        { 
          "sid": "d49b7a4781ea45dcb702825ce30494ba", 
          "name": "list_123" }
        {
          "sid": "e59b7a4781ea45dcb702825ce30495cd", 
          "name": "list_456" 
        }
    ]})
headers = {
  'Content-Type': 'application/json',
  'Authorization': "Basic " + encoding
}

response = requests.request("PUT", url, headers=headers, data=payload)

print(response.text)
package main

import (
	b64 "encoding/base64"
	"fmt"
	"io/ioutil"
	"net/http"
	"strings"
)

func main() {
	// Please provide accountSid, authToken from your Exotel account
	accountSid := "XXXXXXXXX"
	authToken := "YYYYYYYY"
	authKey := "ZZZZZZZZZZ"

	// Encoding the accountSid and authToken, used in Authorization header
	encoding := b64.StdEncoding.EncodeToString([]byte(authKey + ":" + authToken))

	url := "https://<subdomain>/v2/accounts/" + accountSid + "/lists"
	method := "PUT"

	payload := strings.NewReader(`{
	  "lists": [
		  {
			"sid": "d49b7a4781ea45dcb702825ce30494ba",  
                        "name": "list_123"
		  }
                  {
                        "sid": "e59b7a4781ea45dcb702825ce30495cd", 
                        "name": "list_456" 
                  }

	  ]
  }`)

	client := &http.Client{}
	req, err := http.NewRequest(method, url, payload)

	if err != nil {
		fmt.Println(err)
		return
	}
	req.Header.Add("Content-Type", "application/json")
	req.Header.Add("Authorization", "Basic "+encoding)

	res, err := client.Do(req)
	if err != nil {
		fmt.Println(err)
		return
	}
	defer res.Body.Close()

	body, err := ioutil.ReadAll(res.Body)
	if err != nil {
		fmt.Println(err)
		return
	}
	fmt.Println(string(body))
}
{
    "request_id": "b45f202e1ec14b37bc459235a65f8712",
    "method": "POST",
    "http_code": 207,
    "metadata": {
        "failed": 0,
        "total": 2,
        "success": 2     },
    "response": [
        {
            "code": 200,
            "error_data": null,
            "status": "success",
            "data": {
                "sid": "d49b7a4781ea45dcb702825ce30494ba",
                "date_created": "2021-05-23T14:09:32.143446635+05:30",
                "date_updated": "2021-05-23T14:09:32.143446635+05:30",
                "account_sid": "exotel8u3",
                "name": "list_123",
                "uri": "/v2/accounts/exotel8u3/lists/46cd9106113f4920be56811382ebefba",
                "tag": null,
                "contact_count": null
            }
        }
        {
            "code": 200,
            "error_data": null,
            "status": "success",
            "data": {
                "sid": "e59b7a4781ea45dcb702825ce30495cd",
                "date_created": "2021-05-23T14:09:32.143446635+05:30",
                "date_updated": "2021-05-23T14:09:32.143446635+05:30",
                "account_sid": "exotel8u3",
                "name": "list_456",
                "uri": "/v2/accounts/exotel8u3/lists/46cd9106113f4920be56811382ebefba",
                "tag": null,
                "contact_count": null
            }
        }
 ] }

Delete a List

This API allows you to delete an existing list from the Campaign address-book.

DELETE

https://<your_api_key>:<your_api_token><subdomain>/v2/accounts/<your_sid>/lists/<list_id>

  • 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

curl -X DELETE 'https://<your_api_key>:<your_api_token>@<subdomain>/v2/accounts/<account_sid>/lists/<list_sid>'
var unirest = require('unirest');
var unirest = require('unirest');
var accountSid = "XXXXXXXXX";
var accountToken = "YYYYYYYYY";
var authKey = "ZZZZZZZZZZ";

var encoding = Buffer.from(authKey + ':' + accountToken).toString('base64');
var req = unirest('DELETE', 'https://<subdomain>/v2/accounts/'+accountSid+'/lists/<list_sid>')
	.headers({
		Authorization: 'Basic ' + encoding
	})
  .end(function (res) { 
    if (res.error) throw new Error(res.error); 
    console.log(res.raw_body);
  });
<?php

$curl = curl_init();
$accountSid = "XXXXXXXXXX";
$accountToken = "YYYYYYYYYY";
$authKey = "ZZZZZZZZZZ";

$encoding = base64_encode($authKey .":". $accountToken);

curl_setopt_array($curl, array(
  CURLOPT_URL => 'https://<subdomain>/v2/accounts/'+ $accountSid+'/lists/<Clist_id>',
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => '',
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 0,
  CURLOPT_FOLLOWLOCATION => true,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => 'DELETE',
  CURLOPT_HTTPHEADER => array(
    "Authorization: Basic ".$encoding
  ),
));

$response = curl_exec($curl);

curl_close($curl);
echo $response;
import requests
import base64 
import json
accountSid = "XXXXXXXXX"
authToken = "YYYYYYYYY"
authKey = "ZZZZZZZZZZ"

encoding = base64.b64encode(authKey + ":" + authToken)

url = "https://<subdomain>/v2/accounts/"+ accountSid+"/lists/<list_id>"

payload={}
headers = {
    'Authorization': "Basic " + encoding
    }

response = requests.request("DELETE", url, headers=headers, data=payload)

print(response.text)
package main

import (
	b64 "encoding/base64"
	"fmt"
	"io/ioutil"
	"net/http"
)

func main() {
	// Please provide accountSid, authToken from your Exotel account
	accountSid := "XXXXXXXXX"
	authToken := "YYYYYYYY"
	authKey := "ZZZZZZZZZZ"

	// Encoding the accountSid and authToken, used in Authorization header
	encoding := b64.StdEncoding.EncodeToString([]byte(authKey + ":" + authToken))

	url := "https://<subdomain>/v2/accounts/" + accountSid + "/lists/<list_sid>"
	method := "DELETE"

	client := &http.Client{}
	req, err := http.NewRequest(method, url, nil)
	req.Header.Add("Authorization", "Basic "+encoding)

	if err != nil {
		fmt.Println(err)
		return
	}
	res, err := client.Do(req)
	if err != nil {
		fmt.Println(err)
		return
	}
	defer res.Body.Close()

	body, err := ioutil.ReadAll(res.Body)
	if err != nil {
		fmt.Println(err)
		return
	}
	fmt.Println(string(body))
}
{
    "request_id": "df7bbc5e85e84407b063e61eb13a6f4d",
    "method": "DELETE",
    "http_code": 200,
    "response": {
            "code": 200,
            "error_data": null,
            "status": "success",
            "data": {
                "sid": "46cd9106113f4920be56811382ebefba",
                "date_created": "2021-05-23T08:39:32Z",
                "date_updated": "2021-05-23T14:09:32Z",
                "account_sid": "exotel8u3",
                "name": "new-csv_list2",
                "uri": "/v2/accounts/exotel8u3/lists/46cd9106113f4920be56811382ebefba",
                "tag": null,
                "contact_count": null
            }
        }
}

Get Details of a List

This API allows you to fetch details of an existing list using list_ID.

GET

https://<your_api_key>:<your_api_token><subdomain>/v2/accounts/<your_sid>/lists/<list_id>

  • 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

curl -X GET 'https://<your_api_key>:<your_api_token>@<subdomain>/v2/accounts/<account_sid>/lists/<list_sid>'
var unirest = require('unirest');
var unirest = require('unirest');
var accountSid = "XXXXXXXXX";
var accountToken = "YYYYYYYYY";
var authKey = "ZZZZZZZZZZ";

var encoding = Buffer.from(authKey + ':' + accountToken).toString('base64');
var req = unirest('GET', 'https://<subdomain>/v2/accounts/'+accountSid+'/lists/<list_sid>')
	.headers({
		Authorization: 'Basic ' + encoding
	})
  .end(function (res) { 
    if (res.error) throw new Error(res.error); 
    console.log(res.raw_body);
  });
<?php

$curl = curl_init();
$accountSid = "XXXXXXXXXX";
$accountToken = "YYYYYYYYYY";
$authKey = "ZZZZZZZZZZ";

$encoding = base64_encode($authKey .":". $accountToken);

curl_setopt_array($curl, array(
  CURLOPT_URL => 'https://<subdomain>/v2/accounts/'+ $accountSid+'/lists/<list_id>',
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => '',
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 0,
  CURLOPT_FOLLOWLOCATION => true,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => 'GET',
  CURLOPT_HTTPHEADER => array(
    "Authorization: Basic ".$encoding
  ),
));

$response = curl_exec($curl);

curl_close($curl);
echo $response;
import requests
import base64 
import json
accountSid = "XXXXXXXXX"
authToken = "YYYYYYYYY"
authKey = "ZZZZZZZZZZ"

encoding = base64.b64encode(authKey + ":" + authToken)

url = "https://<subdomain>/v2/accounts/"+ accountSid+"/lists/<list_id>"

payload={}
headers = {
    'Authorization': "Basic " + encoding
    }

response = requests.request("GET", url, headers=headers, data=payload)

print(response.text)
package main

import (
	b64 "encoding/base64"
	"fmt"
	"io/ioutil"
	"net/http"
)

func main() {
	// Please provide accountSid, authToken from your Exotel account
	accountSid := "XXXXXXXXX"
	authToken := "YYYYYYYY"
	authKey := "ZZZZZZZZZZ"

	// Encoding the accountSid and authToken, used in Authorization header
	encoding := b64.StdEncoding.EncodeToString([]byte(authKey + ":" + authToken))

	url := "https://<subdomain>/v2/accounts/" + accountSid + "/lists/<list_sid>"
	method := "GET"

	client := &http.Client{}
	req, err := http.NewRequest(method, url, nil)
	req.Header.Add("Authorization", "Basic "+encoding)

	if err != nil {
		fmt.Println(err)
		return
	}
	res, err := client.Do(req)
	if err != nil {
		fmt.Println(err)
		return
	}
	defer res.Body.Close()

	body, err := ioutil.ReadAll(res.Body)
	if err != nil {
		fmt.Println(err)
		return
	}
	fmt.Println(string(body))
}
{
    "request_id": "ee9a44d3b31c488bbcdac3df4dee5a5a",
    "method": "GET",
    "http_code": 200,
    "response": {
            "code": 200,
            "error_data": null,
            "status": "success",
            "data": {
                "sid": "5f392c92b4c9414d940e70e1ff25ad41",
                "date_created": "2021-05-23T06:52:01Z",
                "date_updated": "2021-05-23T12:22:01Z",
                "account_sid": "exotel8u3",
                "name": "21may_csv_list8",
                "uri": "/v2/accounts/exotel8u3/lists/5f392c92b4c9414d940e70e1ff25ad41",
                "tag": null,
                "contact_count": 4
            }
        }
}

Get Bulk Lists

This API allows you get details of lists within an account. This API also allows you to search a particular list by list name and also sort the fetched response by name or date created.

It's a bulk API which which works with offset & limit parameters to fetch specific set of data.

GET

https://<your_api_key>:<your_api_token><subdomain>/v2/accounts/<your_sid>/lists?limit=<limit>&offset=<offset>

  • 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

Request Query Parameters:

Parameter Name   Mandatory/Optional Value

offset

optional

This is the position in the dataset of a particular record. By specifying offset, you retrieve a subset of records starting with the offset value. Offset is zero-based i.e. the 10th record is at offset 9

limit

optional

number of records on single page default:20

name

optional

Search on lists name 

sort_by

optional

This indicates in what order the lists records are sorted in the API response. By default records are sorted by DateCreated in ascending order. However, you can override the same in following way for ascending order: Eg: date_created:asc or name:asc

curl -X GET 'https://<your_api_key>:<your_api_token>@<subdomain>/v2/accounts/<account_sid>/lists?limit=6'
var unirest = require('unirest');
var unirest = require('unirest');
var accountSid = "XXXXXXXXX";
var accountToken = "YYYYYYYYY";
var authKey = "ZZZZZZZZZZ";

var encoding = Buffer.from(authKey + ':' + accountToken).toString('base64');
var req = unirest('GET', 'https://<subdomain>/v2/accounts/'+accountSid+'/lists?limit=<limit>&offset=<offset>')
	.headers({
		Authorization: 'Basic ' + encoding
	})
  .end(function (res) { 
    if (res.error) throw new Error(res.error); 
    console.log(res.raw_body);
  });
<?php

$curl = curl_init();
$accountSid = "XXXXXXXXXX";
$accountToken = "YYYYYYYYYY";
$authKey = "ZZZZZZZZZZ";

$encoding = base64_encode($authKey .":". $accountToken);

curl_setopt_array($curl, array(
  CURLOPT_URL => 'https://<subdomain>/v2/accounts/'+ $accountSid+'/lists?limit=<limit>&offset=<offset>',
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => '',
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 0,
  CURLOPT_FOLLOWLOCATION => true,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => 'GET',
  CURLOPT_HTTPHEADER => array(
    "Authorization: Basic ".$encoding
  ),
));

$response = curl_exec($curl);

curl_close($curl);
echo $response;
import requests
import base64 
import json
accountSid = "XXXXXXXXX"
authToken = "YYYYYYYYY"
authKey = "ZZZZZZZZZZ"

encoding = base64.b64encode(authKey + ":" + authToken)

url = "https://<subdomain>/v2/accounts/"+accountSid+"/lists?limit=<limit>&offset=<offset>"

payload={}
headers = {
    'Authorization': "Basic " + encoding
    }

response = requests.request("GET", url, headers=headers, data=payload)

print(response.text)
package main

import (
	b64 "encoding/base64"
	"fmt"
	"io/ioutil"
	"net/http"
)

func main() {
	// Please provide accountSid, authToken from your Exotel account
	accountSid := "XXXXXXXXX"
	authToken := "YYYYYYYY"
	authKey := "ZZZZZZZZZZ"

	// Encoding the accountSid and authToken, used in Authorization header
	encoding := b64.StdEncoding.EncodeToString([]byte(authKey + ":" + authToken))

	url := "https://<subdomain>/v2/accounts/" + accountSid + "/lists?limit=<limit>&offset=<offset>"
	method := "GET"

	client := &http.Client{}
	req, err := http.NewRequest(method, url, nil)
	req.Header.Add("Authorization", "Basic "+encoding)

	if err != nil {
		fmt.Println(err)
		return
	}
	res, err := client.Do(req)
	if err != nil {
		fmt.Println(err)
		return
	}
	defer res.Body.Close()

	body, err := ioutil.ReadAll(res.Body)
	if err != nil {
		fmt.Println(err)
		return
	}
	fmt.Println(string(body))
}
{
    "request_id": "bb9f1dca63fa4bc484b1918371f988f3",
    "method": "GET",
    "http_code": 200,
    "metadata": {
        "count": 6,
        "offset": 0,
        "limit": 6,
        "total": 44
    },
    "response": [
        {
            "code": 200,
            "error_data": null,
            "status": "success",
            "data": {
                "sid": "a6683f8a0d3a445183cb3e6bbf911f6d",
                "date_created": "2021-05-23T06:54:19Z",
                "date_updated": "2021-05-23T12:24:19Z",
                "account_sid": "exotel8u3",
                "name": "21may_csv_list9",
                "uri": "/v2/accounts/exotel8u3/lists/a6683f8a0d3a445183cb3e6bbf911f6d",
                "tag": null,
                "contact_count": null
            }
        },
        {
            "code": 200,
            "error_data": null,
            "status": "success",
            "data": {
                "sid": "5f392c92b4c9414d940e70e1ff25ad41",
                "date_created": "2021-05-23T06:52:01Z",
                "date_updated": "2021-05-23T12:22:01Z",
                "account_sid": "exotel8u3",
                "name": "21may_csv_list8",
                "uri": "/v2/accounts/exotel8u3/lists/5f392c92b4c9414d940e70e1ff25ad41",
                "tag": null,
                "contact_count": 4
            }
        },
        {
            "code": 200,
            "error_data": null,
            "status": "success",
            "data": {
                "sid": "d996deee9e424c2ea8e07e3dd1856ea9",
                "date_created": "2021-05-21T15:08:18Z",
                "date_updated": "2021-05-21T20:38:17Z",
                "account_sid": "exotel8u3",
                "name": "21may_csv_list1",
                "uri": "/v2/accounts/exotel8u3/lists/d996deee9e424c2ea8e07e3dd1856ea9",
                "tag": null,
                "contact_count": null
            }
        },
        {
            "code": 200,
            "error_data": null,
            "status": "success",
            "data": {
                "sid": "26e1ccb8a66c43cb997e7a6a621419ce",
                "date_created": "2021-05-04T09:53:28Z",
                "date_updated": "2021-05-04T15:23:28Z",
                "account_sid": "exotel8u3",
                "name": "csv_list123",
                "uri": "/v2/accounts/exotel8u3/lists/26e1ccb8a66c43cb997e7a6a621419ce",
                "tag": null,
                "contact_count": null
            }
        },
        {
            "code": 200,
            "error_data": null,
            "status": "success",
            "data": {
                "sid": "98b81a65910646e799c4fac2e3adb191",
                "date_created": "2021-05-04T09:50:05Z",
                "date_updated": "2021-05-04T15:20:04Z",
                "account_sid": "exotel8u3",
                "name": "new_list1",
                "uri": "/v2/accounts/exotel8u3/lists/98b81a65910646e799c4fac2e3adb191",
                "tag": null,
                "contact_count": null
            }
        },
        {
            "code": 200,
            "error_data": null,
            "status": "success",
            "data": {
                "sid": "85288201fd724e9688d206a05d1f30ca",
                "date_created": "2021-05-04T09:49:40Z",
                "date_updated": "2021-05-04T15:19:40Z",
                "account_sid": "exotel8u3",
                "name": "new_list",
                "uri": "/v2/accounts/exotel8u3/lists/85288201fd724e9688d206a05d1f30ca",
                "tag": null,
                "contact_count": null
            }
        }
    ]
}

Get Contacts in a List

This API allows you to fetch all contacts within a list.

It is a Bulk API and supports limit and offset based pagination.

GET

https://<your_api_key>:<your_api_token><subdomain>/v2/accounts/<your_sid>/lists/<list_id>/contacts?offset=<offset_num>&limit=<limit_num>

  • 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

curl -X GET 'https://<your_api_key>:<your_api_token>@<subdomain>/v2/accounts/<account_sid?/lists/<list_sid>/contacts?offset=0&limit=20'
var unirest = require('unirest');
var unirest = require('unirest');
var accountSid = "XXXXXXXXX";
var accountToken = "YYYYYYYYY";
var authKey = "ZZZZZZZZZZ";

var encoding = Buffer.from(authKey + ':' + accountToken).toString('base64');
var req = unirest('GET', 'https://<subdomain>/v2/accounts/'+accountSid+'/lists/<list_sid>/contacts?offset=0')
  .headers({
    Authorization: 'Basic ' + encoding
	})
  .end(function (res) { 
    if (res.error) throw new Error(res.error); 
    console.log(res.raw_body);
  });
<?php

$curl = curl_init();
$accountSid = "XXXXXXXXXX";
$accountToken = "YYYYYYYYYY";
$authKey = "ZZZZZZZZZZ";

$encoding = base64_encode($authKey .":". $accountToken);

curl_setopt_array($curl, array(
  CURLOPT_URL => 'https://<subdomain>/v2/accounts/'+ $accountSid+'/lists/<list_sid>/contacts?offset=0',
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => '',
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 0,
  CURLOPT_FOLLOWLOCATION => true,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => 'GET',
  CURLOPT_HTTPHEADER => array(
    "Authorization: Basic ".$encoding
  ),
));

$response = curl_exec($curl);

curl_close($curl);
echo $response;
import requests
import base64 
import json
accountSid = "XXXXXXXXX"
authToken = "YYYYYYYYY"
authKey = "ZZZZZZZZZZ"

encoding = base64.b64encode(authKey + ":" + authToken)

url = "https://<subdomain>/v2/accounts/"+ accountSid+"/lists/<list_id>/contacts?offset=0"

payload={}
headers = {
    'Authorization': "Basic " + encoding
    }

response = requests.request("GET", url, headers=headers, data=payload)

print(response.text)
package main

import (
	b64 "encoding/base64"
	"fmt"
	"io/ioutil"
	"net/http"
)

func main() {
	// Please provide accountSid, authToken from your Exotel account
	accountSid := "XXXXXXXXX"
	authToken := "YYYYYYYY"
	authKey := "ZZZZZZZZZZ"

	// Encoding the accountSid and authToken, used in Authorization header
	encoding := b64.StdEncoding.EncodeToString([]byte(authKey + ":" + authToken))

	url := "https://<subdomain>/v2/accounts/" + accountSid + "/lists/<list_sid>/contacts?offset=0"
	method := "GET"

	client := &http.Client{}
	req, err := http.NewRequest(method, url, nil)
	req.Header.Add("Authorization", "Basic "+encoding)

	if err != nil {
		fmt.Println(err)
		return
	}
	res, err := client.Do(req)
	if err != nil {
		fmt.Println(err)
		return
	}
	defer res.Body.Close()

	body, err := ioutil.ReadAll(res.Body)
	if err != nil {
		fmt.Println(err)
		return
	}
	fmt.Println(string(body))
}
{
    "request_id": "3f1ffcb8809742e3ac08751f0e2a26e0",
    "method": "GET",
    "http_code": 200,
    "metadata": {
        "count": 6,
        "offset": 0,
        "limit": 20,
        "total": 6
    },
    "response": [
        {
            "code": 200,
            "error_data": null,
            "status": "success",
            "data": {
                "sid": "45f64a6de96e4d50b1e7ccc00d52cb08",
                "date_created": "2021-05-02T14:36:31Z",
                "date_updated": "2021-05-02T14:36:31Z",
                "account_sid": "exotel8u3",
                "number": "+919645122021",
                "first_name": null,
                "last_name": null,
                "company_name": null,
                "email": null,
                "tag": null,
                "custom_field": null,
                "uri": "/v2/accounts/exotel8u3/contacts/45f64a6de96e4d50b1e7ccc00d52cb08"
            }
        },
        {
            "code": 200,
            "error_data": null,
            "status": "success",
            "data": {
                "sid": "d24bf6e934984fd0922b9c4cb48203d6",
                "date_created": "2021-05-02T14:36:31Z",
                "date_updated": "2021-05-02T14:36:31Z",
                "account_sid": "exotel8u3",
                "number": "+919645122029",
                "first_name": null,
                "last_name": null,
                "company_name": null,
                "email": null,
                "tag": null,
                "custom_field": null,
                "uri": "/v2/accounts/exotel8u3/contacts/d24bf6e934984fd0922b9c4cb48203d6"
            }
        },
        {
            "code": 200,
            "error_data": null,
            "status": "success",
            "data": {
                "sid": "58254233e1a84219b9d25b932cf0548c",
                "date_created": "2021-05-02T14:36:42Z",
                "date_updated": "2021-05-02T14:36:42Z",
                "account_sid": "exotel8u3",
                "number": "+919645122020",
                "first_name": null,
                "last_name": null,
                "company_name": null,
                "email": null,
                "tag": null,
                "custom_field": null,
                "uri": "/v2/accounts/exotel8u3/contacts/58254233e1a84219b9d25b932cf0548c"
            }
        },
        {
            "code": 200,
            "error_data": null,
            "status": "success",
            "data": {
                "sid": "b274949c38954135ab1e8340eecc3a0d",
                "date_created": "2021-05-02T14:36:42Z",
                "date_updated": "2021-05-02T14:36:42Z",
                "account_sid": "exotel8u3",
                "number": "+919645122022",
                "first_name": null,
                "last_name": null,
                "company_name": null,
                "email": null,
                "tag": null,
                "custom_field": null,
                "uri": "/v2/accounts/exotel8u3/contacts/b274949c38954135ab1e8340eecc3a0d"
            }
        },
        {
            "code": 200,
            "error_data": null,
            "status": "success",
            "data": {
                "sid": "6b8ebe6428844d98be747ac28000fc29",
                "date_created": "2021-05-02T14:36:54Z",
                "date_updated": "2021-05-02T14:36:54Z",
                "account_sid": "exotel8u3",
                "number": "+919645122023",
                "first_name": null,
                "last_name": null,
                "company_name": null,
                "email": null,
                "tag": null,
                "custom_field": null,
                "uri": "/v2/accounts/exotel8u3/contacts/6b8ebe6428844d98be747ac28000fc29"
            }
        },
        {
            "code": 200,
            "error_data": null,
            "status": "success",
            "data": {
                "sid": "846ab5a7ed844ea394fc176ab892e515",
                "date_created": "2021-05-02T14:36:54Z",
                "date_updated": "2021-05-02T14:36:54Z",
                "account_sid": "exotel8u3",
                "number": "+919645122024",
                "first_name": null,
                "last_name": null,
                "company_name": null,
                "email": null,
                "tag": null,
                "custom_field": null,
                "uri": "/v2/accounts/exotel8u3/contacts/846ab5a7ed844ea394fc176ab892e515"
            }
        }
    ]
}

Delete Contact from a List

This API allows you to remove a contact from a list. It doesn't delete the contact from the campaign address-book, rather just removes the association from the list. To delete the contact permanently, use the API 'Delete a Contact'

DELETE

https://<your_api_key>:<your_api_token><subdomain>/v2/accounts/<your_sid>/lists/<list_sid>/contacts/<contact_sid>

  • 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

curl -X DELETE 'https://<your_api_key>:<your_api_token>@<subdomain>/v2/accounts/Exotel/lists/e46c2fe202904d579ae592d108cf87a0/contacts/d49b7a4781ea45dcb702825ce30494ba'
var unirest = require('unirest');
var unirest = require('unirest');
var accountSid = "XXXXXXXXX";
var accountToken = "YYYYYYYYY";
var authKey = "ZZZZZZZZZZ";
var encoding = Buffer.from(authKey + ':' + accountToken).toString('base64');
var req = unirest('DELETE', 'https://<subdomain>/v2/accounts/Exotel/lists/e46c2fe202904d579ae592d108cf87a0/contacts/d49b7a4781ea45dcb702825ce30494ba')
.headers({
Authorization: 'Basic ' + encoding
	})
  .end(function (res) { 
    if (res.error) throw new Error(res.error); 
    console.log(res.raw_body);
  });
<?php

$curl = curl_init();
$accountSid = "XXXXXXXXXX";
$accountToken = "YYYYYYYYYY";
$authKey = "ZZZZZZZZZZ";

$encoding = base64_encode($authKey .":". $accountToken);

curl_setopt_array($curl, array(
  CURLOPT_URL => 'https://<subdomain>/v2/accounts/Exotel/lists/e46c2fe202904d579ae592d108cf87a0/contacts/d49b7a4781ea45dcb702825ce30494ba',
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => '',
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 0,
  CURLOPT_FOLLOWLOCATION => true,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => 'DELETE',
  CURLOPT_HTTPHEADER => array(
    "Authorization: Basic ".$encoding
  ),
));

$response = curl_exec($curl);

curl_close($curl);
echo $response;
import requests
import base64 
import json
accountSid = "XXXXXXXXX"
authToken = "YYYYYYYYY"
authKey = "ZZZZZZZZZZ"

encoding = base64.b64encode(authKey + ":" + authToken)

url = "https://<subdomain>/v2/accounts/Exotel/lists/e46c2fe202904d579ae592d108cf87a0/contacts/d49b7a4781ea45dcb702825ce30494ba"

payload={}
headers = {
    'Authorization': "Basic " + encoding
    }

response = requests.request("DELETE", url, headers=headers, data=payload)
print(response.text)
package main

import (
	b64 "encoding/base64"
"fmt"
"io/ioutil"
"net/http"
)

func main() {
// Please provide accountSid, authToken from your Exotel account
	accountSid := "XXXXXXXXX"
	authToken := "YYYYYYYY"
	authKey := "ZZZZZZZZZZ"
// Encoding the accountSid and authToken, used in Authorization header
	encoding := b64.StdEncoding.EncodeToString([]byte(authKey + ":" + authToken))

	url := "https://<subdomain>/v2/accounts/Exotel/lists/e46c2fe202904d579ae592d108cf87a0/contacts/d49b7a4781ea45dcb702825ce30494ba"
	method := "DELETE"

	client := &http.Client{}
	req, err := http.NewRequest(method, url, nil)
	req.Header.Add("Authorization", "Basic "+encoding)
if err != nil {
		fmt.Println(err)
return
}
	res, err := client.Do(req)
if err != nil {
		fmt.Println(err)
return
}
	defer res.Body.Close()

	body, err := ioutil.ReadAll(res.Body)
if err != nil {
		fmt.Println(err)
return
}
	fmt.Println(string(body))
}
{
    "request_id":"cfa7d61f24064a399789d677ef0cc379",
    "method":"DELETE",
    "http_code":200,
    "response":{
          "code":200,
          "error_data":null,
          "status":"success",
          "data":{
                    "sid":"d49b7a4781ea45dcb702825ce30494ba",
                    "date_created":"2017-12-05T14:15:51.108069088+05:30",
                    "date_updated":"2017-12-05T14:15:51.108069088+05:30",
                    "account_sid":"Exotel",
                    "list_id":"e46c2fe202904d579ae592d108cf87a0",
                    "uri":"/v2/Accounts/Exotel/contacts/d49b7a4781ea45dcb702825ce30494ba"
                 }
       }
}