×

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