Create Contacts

This is a bulk API, which can create one or more contacts. The contacts created with this API gets added to the Campaigns Addressbook and can only be used in Campaigns. These contacts can be used to create a List using the 'Campaign - Lists' APIs listed below.

A max of 5000 contacts can be created in a single request. 

POST

https://<your_api_key>:<your_api_token><subdomain>/v2/accounts/<your_sid>/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

The following are the POST parameters:

Parameter Name   Mandatory/Optional Value
number Mandatory

The phone number of the contact that will be called in a campaign. It should be in E.164 format. If not set, our system will try to match it with a country and make a call. If landline number, prefix it with STD code; Ex: 0XXXXXX2400

first_name Optional The first name of the contact
last_name Optional The last name of the contact
company_name Optional The company name of the contact
email Optional The email ID of the contact
tag Optional The tag with which this contact will be associated with
custom Optional Custom field to allow you to pass any number of key value pairs in JSON format
curl -X POST 'https://<your_api_key>:<your_api_token>@<subdomain>/v2/accounts/<your_sid>/contacts' \
--header 'Content-Type: application/json' \
--data-raw '{
    "contacts": [
        {
            "number": "+91910XXXXX10",
            "first_name": "captain",
            "last_name": "exotel",
            "company_name": "Exotel",
            "email": "captain@email.com",
            "tag": "Member",
            "custom_field": {
                "key": {
                    "key1": "values1"
                }
            }
        },
        {
            "number": "+91910YYYYY10",
            "first_name": "captain",
            "last_name": "exotel",
            "company_name": "Exotel",
            "email": "captain@email.com",
            "tag": "Technician",
            "custom_field": {
                "key": {
                    "key1": "values1"
                }
            }
        }
    ]
}'
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+"/contacts")
  .headers({
	  Authorization: 'Basic ' + encoding,
	  'Content-Type': 'application/json'
  })
  .send(JSON.stringify({"contacts":[
      {
				"number":"+919100YYYY10",
				"first_name":"captain",
				"last_name":"exotel",
				"company_name":"Exotel",
				"email":"captain@email.com",
				"tag":"Member",
				"custom_field":{
						"key":{"key1":"values1"}
					}
			},
			{
				"number":"+919100XXXX10",
				"first_name":"captain",
				"last_name":"exotel",
				"company_name":"Exotel",
				"email":"captain@email.com",
				"tag":"Technician",
				"custom_field":{
					"key":{"key1":"values1"}
				}
			}
		]}))
  .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/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 =>'{
    "contacts": [
        {
            "number": "+919100YYYY10",
            "first_name": "captain",
            "last_name": "exotel",
            "company_name": "Exotel",
            "email": "captain@email.com",
            "tag": "Member",
            "custom_field": {
                "key": {
                    "key1": "values1"
                }
            }
        },
        {
            "number": "+919100XXXX10",
            "first_name": "captain",
            "last_name": "exotel",
            "company_name": "Exotel",
            "email": "captain@email.com",
            "tag": "Technician",
            "custom_field": {
                "key": {
                    "key1": "values1"
                }
            }
        }
    ]
}',
  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+"/contacts"

payload = json.dumps({
    "contacts": [
        {
            "number": "+919100YYYY10",
            "first_name": "captain",
            "last_name": "exotel",
            "company_name": "Exotel",
            "email": "captain@email.com",
            "tag": "Member",
            "custom_field": {
                "key": {
                    "key1": "values1"
                }
            }
        },
        {
            "number": "+919100XXXX10",
            "first_name": "captain",
            "last_name": "exotel",
            "company_name": "Exotel",
            "email": "captain@email.com",
            "tag": "Technician",
            "custom_field": {
                "key": {
                    "key1": "values1"
                }
            }
        }
    ]
})

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 + "/contacts"
	method := "POST"

	payload := strings.NewReader(`{
    "contacts": [
        {
            "number": "+919100000010",
            "first_name": "captain",
            "last_name": "exotel",
            "company_name": "Exotel",
            "email": "captain@email.com",
            "tag": "Member",
            "custom_field": {
                "key": {
                    "key1": "values1"
                }
            }
        },
        {
            "number": "+919100000010",
            "first_name": "captain",
            "last_name": "exotel",
            "company_name": "Exotel",
            "email": "captain@email.com",
            "tag": "Member",
            "custom_field": {
                "key": {
                    "key1": "values1"
                }
            }
        }
    ]
}`)

	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))
}

HTTP Response:

  • Response for this request will be 207 - Multi Status, and each individual contact data will have their respective responses of 200 OK or 400. In case of non success message, the response body will contain the error message.
  • The sid is the unique identifier of the contact, and it will be useful to log this for future reference
  • HTTP body will contain an JSON similar to the one below
{
    "request_id": "e83d8ff8a2d2489d852bdaa7067aa9d2",
    "method": "POST",
    "http_code": 207,
    "metadata": {
        "failed": 0,
        "total": 2,
        "success": 2
    },
    "response": [
        {
            "code": 200,
            "error_data": null,
            "status": "success",
            "data": {
                "sid": "4440b6e1a85f489b87d76d8779956caf",
                "date_created": "2021-05-23T13:51:30.15101622+05:30",
                "date_updated": "2021-05-23T13:51:30.15101622+05:30",
                "account_sid": "exotel8u3",
                "number": "+919101234511",
                "first_name": "captain",
                "last_name": "exotel",
                "company_name": "Exotel",
                "email": "captain@email.com",
                "tag": "API",
                "custom_field": {
                    "key": {
                        "key1": "values1"
                    }
                },
                "uri": "/v2/accounts/exotel8u3/contacts/4440b6e1a85f489b87d76d8779956caf"
            }
        },
        {
            "code": 200,
            "error_data": null,
            "status": "success",
            "data": {
                "sid": "83ba26b7f11c4e75b4043c8b33ceba49",
                "date_created": "2021-05-23T13:51:30.151051039+05:30",
                "date_updated": "2021-05-23T13:51:30.151051039+05:30",
                "account_sid": "exotel8u3",
                "number": "+919101234510",
                "first_name": "captain",
                "last_name": "exotel",
                "company_name": "Exotel",
                "email": "captain@email.com",
                "tag": "Technician",
                "custom_field": {
                    "key": {
                        "key1": "values1"
                    }
                },
                "uri": "/v2/accounts/exotel8u3/contacts/83ba26b7f11c4e75b4043c8b33ceba49"
            }
        }
    ]
}

Description of response parameter:

Parameter Name   Mandatory/Optional Value
request_id Mandatory

Unique UUID to identify the request

method Mandatory

HTTP method (post/delete/get/put)

http_code Mandatory HTTP Code of the response
metadata Mandatory

Count of failed, total and success records

response.code Mandatory

Http Code of each contact, in case of partial success (207)

response.error_data Mandatory

Error data of each contact

status Mandatory

failed/success 


Update a Contact

This API allows you to update an existing contact.

PUT

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

  • 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 --location --request PUT 'https://<your_api_key>:<your_api_token>@<subdomain>/v2/accounts/<account_sid>/contacts/<contact_sid>' \
--header 'Content-Type: application/json' \
--data-raw '{
            "first_name": "XYZ"
        }'
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/contacts/<contact_sid>')
  .headers({
      Authorization: 'Basic ' + encoding,
      'Content-Type': 'application/json'
  })
  .send(JSON.stringify({"first_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/contacts/<contact_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 =>'{
            "first_name": "captain"
}',
  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/contacts/<contact_sid>"

payload = json.dumps(
        {
            "first_name": "captain"
        }
        )
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 + "/contacts/<contact_sid>"
	method := "PUT"

	payload := strings.NewReader(`{
			  "first_name": "captain"
		  }`)

	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": "4fe1e055e71947658517030d7f933d85",
    "method": "PUT",
    "http_code": 200,
    "response":{
            "code": 200,
            "error_data": null,
            "status": "success",
            "data": {
                "sid": "83ba26b7f11c4e75b4043c8b33ceba49",
                "date_created": "2021-05-23T08:21:30Z",
                "date_updated": "2021-05-23T08:27:17Z",
                "account_sid": "exotel8u3",
                "number": "+919101234510",
                "first_name": "captain2.0",
                "last_name": "exotel",
                "company_name": "Exotel",
                "email": "captain@email.com",
                "tag": "Technician",
                "custom_field": {
                    "key": {
                        "key1": "values1"
                    }
                },
                "uri": "/v2/accounts/exotel8u3/contacts/83ba26b7f11c4e75b4043c8b33ceba49"
            }
        }
}

Update Bulk Contacts

This API allows you to update more than one contact at a time.

PUT

https://<your_api_key>:<your_api_token><subdomain>/v2/accounts/<your_sid>/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 --location --request PUT 'https://<your_api_key>:<your_api_token>@<subdomain>/v2/accounts/<account_sid>/contacts' \
--header 'Content-Type: application/json' \
--data-raw '
{
    "contacts": [
        {
            "sid":"83ba26b7f11c4e75b4043c8b33ceba49",   
            "first_name": "XYZ" 
        }
        { 
            "sid":"93ba26b7f11c4e75b4043c8b33ceba59",
            "first_name": "ABC" 
         } 
         { 
            "sid":"73ba26b7f11c4e75b4043c8b33ceba69",
            "first_name": "LMN" 
         } 
    ] 
}'
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/contacts')
  .headers({
      Authorization: 'Basic ' + encoding,
      'Content-Type': 'application/json'
  })
  .send(JSON.stringify(
{
    "contacts": [
        {
            "sid":"83ba26b7f11c4e75b4043c8b33ceba49",
            "first_name": "XYZ" 
        }
        { 
            "sid":"93ba26b7f11c4e75b4043c8b33ceba59",
            "first_name": "ABC" 
         } 
         { 
            "sid":"73ba26b7f11c4e75b4043c8b33ceba69",
            "first_name": "LMN" 
         } 
    ] 
}
)
  .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/contacts/<contact_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 =>'
{
    "contacts": [
        {
            "sid":"83ba26b7f11c4e75b4043c8b33ceba49", 
            "first_name": "XYZ" 
        }
        { 
            "sid":"93ba26b7f11c4e75b4043c8b33ceba59",
            "first_name": "ABC" 
         } 
         { 
            "sid":"73ba26b7f11c4e75b4043c8b33ceba69",
            "first_name": "LMN" 
         } 
    ] 
}',
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/contacts/<contact_sid>"

payload = json.dumps(
{
    "contacts": [
        {
            "sid":"83ba26b7f11c4e75b4043c8b33ceba49",        
            "first_name": "XYZ" 
        }
        { 
            "sid":"93ba26b7f11c4e75b4043c8b33ceba59",
            "first_name": "ABC" 
         } 
         { 
            "sid":"73ba26b7f11c4e75b4043c8b33ceba69",
            "first_name": "LMN" 
         } 
    ] 
}
)
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 + "/contacts/<contact_sid>"
	method := "PUT"

	payload := strings.NewReader(
{
    "contacts": [
        {
            "sid":"83ba26b7f11c4e75b4043c8b33ceba49",
            "first_name": "XYZ" 
        }
        { 
            "sid":"93ba26b7f11c4e75b4043c8b33ceba59",
            "first_name": "ABC" 
         } 
         { 
            "sid":"73ba26b7f11c4e75b4043c8b33ceba69",
            "first_name": "LMN" 
         } 
    ] 
}
)

	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":"a325d397a29f49698113ad56715dcf23",
  "method":"PUT",
  "http_code":207,
  "metadata":
     {
       "failed":2,
       "total":3,
       "success":1
     },
  "response":[
     {
       "code":200,
       "error_data":null,
       "status":"success",
       "data":{
           "sid":"83ba26b7f11c4e75b4043c8b33ceba49", 
           "date_created":"2017-11-30T11:22:39Z", 
           "date_updated":"2017-12-05T14:24:11Z", 
           "account_sid":"Exotel", 
           "number":"+67420336456", 
           "first_name":"XYZ", 
           "last_name":"ABC", 
           "company_name":"Exotel",
           "email":"shiva@exotel.in",
           "tag":"Member",
           "custom_field":{ "key":{ "a":"b", "c":[1,2,3] } }, 
           "uri":"/v2/Accounts/Exotel/Contacts/4675ce5f21994bcca8cf07c7e0426be7" 
        } 
      }, 
   { 
     "code":404, 
     "error_data":
        { 
           "code":1000, 
           "description":"Contact not found", 
           "message":"Not Found" 
        }, 
     "status":"failure" 
   }, 
   { 
     "code":404, 
     "error_data":
       { 
          "code":1000, 
          "description":"Contact not found", 
          "message":"Not Found" 
       }, 
     "status":"failure" 
   } 
] 
}

Get Details of a Contact

This API allows you to fetch details of a single contact based upon a Contact Sid.

GET

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

  • 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 -XGET 'https://<your_api_key>:<your_api_token>@<subdomain>/v2/accounts/<account_sid>/contacts/<contact_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+'/contacts/<contact_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+'/contacts/<contact_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+"/contacts/<contact_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 + "/contacts/<contact_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": "c70db03fca594e1fab4f01ffc2e1f31b",
    "method": "GET",
    "http_code": 200,
    "response":{
            "code": 200,
            "error_data": null,
            "status": "success",
            "data": {
                "sid": "83ba26b7f11c4e75b4043c8b33ceba49",
                "date_created": "2021-05-23T08:21:30Z",
                "date_updated": "2021-05-23T08:21:30Z",
                "account_sid": "exotel8u3",
                "number": "+919101234510",
                "first_name": "captain",
                "last_name": "exotel",
                "company_name": "Exotel",
                "email": "captain@email.com",
                "tag": "Technician",
                "custom_field": {
                    "key": {
                        "key1": "values1"
                    }
                },
                "uri": "/v2/accounts/exotel8u3/contacts/83ba26b7f11c4e75b4043c8b33ceba49"
            }
        }
}

Get Details of Bulk Contacts

This API allows you to fetch details of bulk contacts.

It supports limit and offset based pagination. Maximum records per page is 20.

GET

https://<your_api_key>:<your_api_token><subdomain>/v2/accounts/<your_sid>/contacts?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 by Campaign name 

sort_by

optional

This indicates in what order the campaign 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

list_sids

optional

fetch the details of contacts belonging to a particular list

filter

optional

If filter is “show_list” Response will contain associated list data too in contacts. 

curl -XGET 'https://<your_api_key>:<your_api_token>@<subdomain>/v2/accounts/exotel8u3/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+'/contacts?offset=0&limit=20')
  .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+'/contacts?offset=0&limit=20',
  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/exotel8u3/contacts?offset=0&limit=20"

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 + "/contacts?offset=0&limit=10"
	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 A Contact

This API allows a contact to be deleted by passing the Contact Sid in the request.

DELETE

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

  • 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>/contacts/<contact_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+'/contacts/<contact_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+'/contacts/<Ccontact_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+"/contacts/<contact_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 + "/contacts/<contact_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": "e623a09f108d4fe0b5c442024f3d30bb",
    "method": "DELETE",
    "http_code": 200,
    "response": {
            "code": 200,
            "error_data": null,
            "status": "success",
            "data": {
                "sid": "4440b6e1a85f489b87d76d8779956caf",
                "date_created": "2021-05-23T08:21:30Z",
                "date_updated": "2021-05-23T08:21:30Z",
                "account_sid": "exotel8u3",
                "number": "+919101234511",
                "first_name": "captain",
                "last_name": "exotel",
                "company_name": "Exotel",
                "email": "captain@email.com",
                "tag": "API",
                "custom_field": {
                    "key": {
                        "key1": "values1"
                    }
                },
                "uri": "/v2/accounts/exotel8u3/contacts/4440b6e1a85f489b87d76d8779956caf"
            }
        }
}