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 (if the type is static) 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'.
If the type is selected as dynamic, a maximum of 5 lakhs contacts can be uploaded with upto 5 variables. Please make sure the filz size is less than 60 MB and type should be dynamic.
https://<your_api_key>:<your_api_token><subdomain>/v2/accounts/<your_sid>/contacts/csv-upload
This API supports MULTIPART/FORM-DATA in the request & JSON in response.
<your_api_key>
and <your_api_token>
with the API key and token created by you.<your_sid>
with your “Account sid”<subdomain>
with the region of your account
<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 |
file_name | Mandatory | The local path of the file which will be used to upload the contacts. |
type | Optional |
static or dynamic choose dynamic if you want to use the contact's metadata (required to personalize call/sms) |
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", "file_name":"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 } } } }
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.
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 } } } }