×

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"
            }
        }
    ]
}