Exotel Developer Portal

To get details of calls in bulk (including Status, Price, etc.), you will need to make a HTTP GET request to

Note that Bulk Call Details will not provide ongoing calls’ details

GET

https://<your_api_key>:<your_api_token><subdomain>/v1/Accounts/<your_sid>/Calls

If you’d prefer response in JSON format, just append .json at the end like …/Calls.json

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

Please make sure to URL encode query parameters in the HTTP GET request.

Description of request query parameters (filters):

Parameter Name	Description
Sid	string; an alpha-numeric unique identifier of the call One or multiple Call SIDs which are comma separated. Recommended limit of SIDs which should be passed together is 20 and maximum allowed limit is 100. If DateCreated is not set, it will only check for last 31 days by default. While querying Sid(s) older than 31 days, DateCreated filter needs to be provided. Example: /Calls?Sid=48d690c837bb0c755a1228dcb6911416,d7d9cefd9773dd746d8f1e029cdb1417 /Calls?Sid=48d690c837bb0c755a1228dcb6911416&DateCreated=gte:2019-01-01 00:00:00;lte:2019-01-31 23:59:59
DateCreated	Date and time at which the Call resource was created in the Exotel system. Supported operators (gte and lte), for more info refer to filter operators section below. You can query call records only up to 6 months old and provide maximum date range of 1 month. Default if not set: Last 31 days Example: /Calls?DateCreated=gte:2019-01-01 00:00:00;lte:2019-01-31 23:59:59
To	Your customer's phone number. One or multiple To numbers can be provided (in E.164 format) which are comma separated. (max limit: 5) Example: /Calls?To=<number-1> /Calls?To=<number-1>,<number-2>"
From	The phone number that will be called first. One or multiple From numbers can be provided (in E.164 format) which are comma separated. (max limit: 5) Example: /Calls?From=<number-1> /Calls?From=<number-1>,<number-2>,...
Status	Overall call status, which could be one of: completed - The call was answered and has ended normally failed - The call could not be completed as dialled, most likely because the phone number was non-existent busy - The caller received a busy signal no-answer - The call ended without being answered Example: /Calls?Status=completed /Calls?Status=failed,no-answer,busy,canceled
Duration	Call duration in seconds. Supported operators (gte, eq and lte), for more info refer to filter operators section below. Example: /Calls?Duration=gte:10s;lte:45s /Calls?Duration=eq:30s
Price	If present, this will be the amount (as per your billing currency) you have been charged for the call. Supported operators (gte, eq and lte), for more info refer to filter operators section below. Example: /Calls?Price=gte:0.10;lte:1.0 /Calls?Price=eq:0.300030
Direction	inbound outbound-dial - Outbound calls from Exotel dashboard outbound-api - All other Outbound calls (API, campaign etc.) Example: /Calls?Direction=inbound /Calls?Direction=outbound-dial,inbound
PhoneNumber	This represents the Virtual Number (ExoPhone) used for the call. One or multiple PhoneNumber(s) can be provided (in E.164 format) which are comma separated. (max limit: 5) Example: /Calls?PhoneNumber=<vn-1> /Calls?PhoneNumber=<vn-1>,<vn-2>,...
PageSize	This represents number of records visible in one page of the API response. Default: 50, Max: 100
SortBy	This indicates in what order the Call records are sorted in the API response. By default records are sorted by DateCreated in descending order. However, you can override the same in following way for ascending order: Example: /Calls?SortBy=DateCreated:asc
Before	Auto generated unique string returned in the PrevPageUri (under Metadata) to be used as query param when at least one record is returned in that page. The value of this field is a cursor which identifies a call record uniquely.
After	Auto generated unique string returned in the NextPageUri (under Metadata) to be used as query param when at least one record is present in that page. The value of this field is a cursor which identifies a call record uniquely.

Filter Operators (Please note these operators are only applicable to certain query parameters as mentioned above)

Operator	Description	Examples
eq:	Equals	Return results where duration is exactly ten seconds: Duration=eq:10s Same can also be written as Duration=10s
gte:	Greater than or equal to	Return results where Duration is ten seconds or more: Duration=gte:10s
lte:	Less than or equal to	Return results where Duration is ten seconds or less: Duration=lte:10s
,	OR operator	OR operator (,) is used to select multiple values if any one of them matches
;	AND operator	AND operator (;) is used to select multiple values if all of them matches. Url encode ; to %3B while making the API request.

curl https://<your_api_key>:<your_api_token><subdomain>/v1/Accounts/<your_sid>/Calls

var request = require('request');

var options = {
    url: 'https://<your_api_key>:<your_api_token><subdomain>/v1/Accounts/<your_sid>/Calls'
};

function callback(error, response, body) {
    if (!error && response.statusCode == 200) {
        console.log(body);
    }
}

request(options, callback);

<?php
include('vendor/rmccue/requests/library/Requests.php');
Requests::register_autoloader();
$headers = array();
$response = Requests::get('https://<your_api_key>:<your_api_token><subdomain>/v1/Accounts/<your_sid>/Calls', $headers);

import requests

requests.get('https://<your_api_key>:<your_api_token><subdomain>/v1/Accounts/<your_sid>/Calls')

require 'net/http'
require 'uri'

uri = URI.parse("https://<your_api_key>:<your_api_token><subdomain>/v1/Accounts/<your_sid>/Calls")
response = Net::HTTP.get_response(uri)

# response.code
# response.body

HTTP Response:

On success, the HTTP response status code will be 200
the HTTP response body will contain an JSON/XML similar to the one below

Example Response
JSON
XML

{
    "Metadata": {
        "Total": 1027,
        "PageSize": 1,
        "FirstPageUri": "/v1/Accounts/<your_sid>/Calls.json?PageSize=2&DateCreated=gte%3A2020-01-01+00%3A00%3A00%3Blte%3A2020-01-03+00%3A00%3A00&SortBy=DateCreated:desc",
        "PrevPageUri": "/v1/Accounts/<your_sid>/Calls.json?PageSize=2&DateCreated=gte%3A2020-01-01+00%3A00%3A00%3Blte%3A2020-01-03+00%3A00%3A00&SortBy=DateCreated:desc&Before=MTU3Nzk4NjAwNixhZmQ4MGJhNzI1MzA5YmU2MjM0MTA2YjY5ZGVmMTQxMg==",
        "NextPageUri": "/v1/Accounts/<your_sid>/Calls.json?PageSize=2&DateCreated=gte%3A2020-01-01+00%3A00%3A00%3Blte%3A2020-01-03+00%3A00%3A00&SortBy=DateCreated:desc&After=MTU3Nzk4NDQwNywwNmQ4ZmI0MDdlZWY5N2YxZmI0OTllNjZjOTI5MTQxMg=="
    },
    "Calls": [
        {
            "Sid": "b6cfaf5f5cef3ca0fc937749ef960e25",
            "ParentCallSid": "",
            "DateCreated": "2016-11-29 15:58:45",
            "DateUpdated": "2016-11-29 16:00:09",
            "AccountSid": "Exotel",
            "To": "0XXXXX20000",
            "From": "0XXXXX30240",
            "PhoneNumberSid": "0XXXXXX4890",
            "Status": "completed",
            "StartTime": "2016-11-29 15:59:10",
            "EndTime": "2016-11-29 15:59:27",
            "Duration": "17",
            "Price": "1.500",
            "Direction": "outbound-api",
            "AnsweredBy": "human",
            "ForwardedFrom": "",
            "CallerName": "",
            "Uri": "/v1/Accounts/<your_sid>/Calls/b6cfaf5f5cef3ca0fc937749ef960e25",
            "RecordingUrl": "https://s3-ap-southeast-1.amazonaws.com/exotelrecordings/<your_sid>/b6cfaf5f5cef3ca0fc937749ef960e25.mp3"
        }
    ]
}

<?xml version="1.0" encoding="UTF-8"?>
<TwilioResponse>
    <Metadata>
        <Total>1027</Total>
        <PageSize>1</PageSize>
        <FirstPageUri>/v1/Accounts/Exotel/Calls?PageSize=2&amp;DateCreated=gte%3A2020-01-01+00%3A00%3A00%3Blte%3A2020-01-03+00%3A00%3A00&amp;SortBy=DateCreated:desc</FirstPageUri>
        <PrevPageUri>/v1/Accounts/Exotel/Calls?PageSize=2&amp;DateCreated=gte%3A2020-01-01+00%3A00%3A00%3Blte%3A2020-01-03+00%3A00%3A00&amp;SortBy=DateCreated:desc&amp;Before=MTU3Nzk4NjAwNixhZmQ4MGJhNzI1MzA5YmU2MjM0MTA2YjY5ZGVmMTQxMg==</PrevPageUri>
        <NextPageUri>/v1/Accounts/Exotel/Calls?PageSize=2&amp;DateCreated=gte%3A2020-01-01+00%3A00%3A00%3Blte%3A2020-01-03+00%3A00%3A00&amp;SortBy=DateCreated:desc&amp;After=MTU3Nzk4NDQwNywwNmQ4ZmI0MDdlZWY5N2YxZmI0OTllNjZjOTI5MTQxMg==</NextPageUri>
    </Metadata>
 <Call>
  <Sid>b6cfaf5f5cef3ca0fc937749ef960e25</Sid>
  <ParentCallSid></ParentCallSid>
  <DateCreated>2017-02-17 14:16:03</DateCreated>
  <DateUpdated>2017-02-17 14:17:32</DateUpdated>
  <AccountSid>Exotel</AccountSid>
  <To>0XXXXX20000</To>
  <From>0XXXXX30240</From>
  <PhoneNumberSid>0XXXXXX4890</PhoneNumberSid>
  <Status>completed</Status>
  <StartTime>2017-02-17 14:16:03</StartTime>
  <EndTime>2017-02-17 14:16:20</EndTime>
  <Duration>17</Duration>
  <Price>0.750</Price>
  <Direction>inbound</Direction>
  <AnsweredBy>human</AnsweredBy>
  <ForwardedFrom></ForwardedFrom>
  <CallerName></CallerName>
  <Uri>/v1/Accounts/<your_sid>/Calls/b6cfaf5f5cef3ca0fc937749ef960e25</Uri>
  <RecordingUrl>https://s3-ap-southeast-1.amazonaws.com/exotelrecordings/<your_sid>/b6cfaf5f5cef3ca0fc937749ef960e25.mp3</RecordingUrl>
 </Call>
</TwilioResponse>

Some of the parameters of a call (like Duration, Price, EndTime, etc.) are updated asynchronously after the call ends. So it might take some time after the call ends (~ 2 mins on an average) for these parameters to be populated correctly.

Description of parameters under 'Metadata' object mentioned in the above response:

Parameter Name	Type & Value
Total	Number of call records matching the given query and filters at that point of time
PageSize	This indicates the number of records on that page
FirstPageUri	This indicates the URI of the first page as per the request. This can be used to to retrieve call records from the beginning of the page.
PrevPageUri	This indicates the URI of the previous page as per the request. This can be used to to retrieve previous set of call records.
NextPageUri	This indicates the URI of the next page as per the request. This can be used to to retrieve next set of call records.

Description of parameters under 'Calls' array object mentioned in the above response:

Parameter Name	Type & Value
Sid	string; an alpha-numeric unique identifier of the call
DateCreated	Date and time at which the user initiated the API
DateUpdated	Date and time at which the status of the call was last updated in our system
AccountSid	Your account SID
To	Your customer's phone number in E.164 format
From	The phone number that will be called first in E.164 format
PhoneNumber	This is your ExoPhone/Exotel Virtual Number in E.164 format
PhoneNumberSid	This is the SID (unique ID)of the ExoPhone/Exotel Virtual Number. It can be same as the ExoPhone number or UUID based on when your number was configured.
Status	Overall call status, which could be one of: completed - The call was answered and has ended normally failed - The call could not be completed as dialled, most likely because the phone number was non-existent busy - The caller received a busy signal no-answer - The call ended without being answered
StartTime	Time in format YYYY-MM-DD HH:mm:ss; Date and time when the call request was initiated to the operator
EndTime	Time in format YYYY-MM-DD HH:mm:ss; Date and time when the call was completed
Duration	Call duration in seconds
Price	Double; If present, this will be the amount (in INR or USD) you have been charged for the call
Direction	inbound outbound-dial - Outbound calls from Exotel dashboard outbound-api - All other Outbound calls (API, campaign etc.)
AnsweredBy	human
Uri	Uri is the path of the CallSid
RecordingUrl	Link to the call recording

If additional information such as status of both the call legs are required, you will need to make an HTTP GET request as:

GET

https://<your_api_key>:<your_api_token><subdomain>/v1/Accounts/<your_sid>/Calls?details=true

HTTP Response:

On success, the HTTP response status code will be 200
the HTTP body will contain an XML similar to the one below

Example Response
JSON
XML

{
    "Metadata": {
        "Total": 1027,
        "PageSize": 1,
        "FirstPageUri": "/v1/Accounts/<your_sid>/Calls.json?PageSize=2&DateCreated=gte%3A2020-01-01+00%3A00%3A00%3Blte%3A2020-01-03+00%3A00%3A00&SortBy=DateCreated:desc&details=true",
        "PrevPageUri": "/v1/Accounts/<your_sid>/Calls.json?PageSize=2&DateCreated=gte%3A2020-01-01+00%3A00%3A00%3Blte%3A2020-01-03+00%3A00%3A00&SortBy=DateCreated:desc&details=true&amp;Before=MTU3Nzk4NjAwNixhZmQ4MGJhNzI1MzA5YmU2MjM0MTA2YjY5ZGVmMTQxMg==",
        "NextPageUri": "/v1/Accounts/<your_sid>/Calls.json?PageSize=2&DateCreated=gte%3A2020-01-01+00%3A00%3A00%3Blte%3A2020-01-03+00%3A00%3A00&SortBy=DateCreated:desc&details=true&After=MTU3Nzk4NDQwNywwNmQ4ZmI0MDdlZWY5N2YxZmI0OTllNjZjOTI5MTQxMg=="
    },
    "Calls": [
        {
            "Sid": "b6cfaf5f5cef3ca0fc937749ef960e25",
            "ParentCallSid": "",
            "DateCreated": "2016-11-29 15:58:45",
            "DateUpdated": "2016-11-29 16:00:09",
            "AccountSid": "Exotel",
            "To": "0XXXXX20000",
            "From": "0XXXXX30240",
            "PhoneNumberSid": "0XXXXXX4890",
            "Status": "completed",
            "StartTime": "2016-11-29 15:59:10",
            "EndTime": "2016-11-29 15:59:57",
            "Duration": "47",
            "Price": "1.500",
            "Direction": "outbound-api",
            "AnsweredBy": "human",
            "ForwardedFrom": "",
            "CallerName": "",
            "Uri": "/v1/Accounts/<your_sid>/Calls/b6cfaf5f5cef3ca0fc937749ef960e25",
            "RecordingUrl": "https://s3-ap-southeast-1.amazonaws.com/exotelrecordings/<your_sid>/b6cfaf5f5cef3ca0fc937749ef960e25.mp3",
            "Details": {
                "ConversationDuration": 33,
                "Legs": [
                    {
                        "Leg": {
                            "Id": 1,
                            "OnCallDuration": 43
                        }
                    },
                    {
                        "Leg": {
                            "Id": 2,
                            "OnCallDuration": 33
                        }
                    }
                ],
                "Leg1Status": "completed",
                "Leg2Status": "no-answer"
            }
        }
    ]
}

<?xml version="1.0" encoding="UTF-8"?>
<TwilioResponse>
    <Metadata>
        <Total>1027</Total>
        <PageSize>1</PageSize>
        <FirstPageUri>/v1/Accounts/Exotel/Calls?PageSize=100&amp;SortBy=DateCreated:desc&amp;Status=completed&amp;details=true&amp;NumbersMetadata=true</FirstPageUri>
        <PrevPageUri>/v1/Accounts/Exotel/Calls?PageSize=100&amp;SortBy=DateCreated:desc&amp;Status=completed&amp;details=true&amp;NumbersMetadata=true&amp;Before=MTU3ODUwMjgwMyxiNTM2MzgzNzZlZWMyYTUxNjVmZGVlZmU2OWQyMTQxOA==</PrevPageUri>
        <NextPageUri>/v1/Accounts/Exotel/Calls?PageSize=100&amp;SortBy=DateCreated:desc&amp;Status=completed&amp;details=true&amp;NumbersMetadata=true&amp;After=MTU3ODQ4NTE2OSwwNjYwMDJiOWE2MmZiN2IxMmE0YjljODAzNTZmMTQxOA==</NextPageUri>
    </Metadata>
    <Call>
        <Sid>b6cfaf5f5cef3ca0fc937749ef96d245</Sid>
        <ParentCallSid></ParentCallSid>
        <DateCreated>2016-11-29 15:58:45</DateCreated>
        <DateUpdated>2016-11-29 16:00:09</DateUpdated>
        <AccountSid>Exotel</AccountSid>
        <To>0XXXXX30240</To>
        <From>0XXXXX85175</From>
        <PhoneNumberSid>0XXXXXX4890</PhoneNumberSid>
        <Status>completed</Status>
        <StartTime>2016-11-29 15:59:10</StartTime>
        <EndTime>2016-11-29 15:59:27</EndTime>
        <Duration>17</Duration>
        <Price>1.500</Price>
        <Direction>outbound-api</Direction>
        <AnsweredBy>human</AnsweredBy>
        <ForwardedFrom></ForwardedFrom>
        <CallerName></CallerName>
        <Uri>/v1/Accounts/Exotel/Calls/b6cfaf5f5cef3ca0fc937749ef96d245</Uri>
        <RecordingUrl>https://s3-ap-southeast-1.amazonaws.com/exotelrecordings/Exotel/b6cfaf5f5cef3ca0fc937749ef96d245.mp3</RecordingUrl>
        <Details>
            <ConversationDuration>8</ConversationDuration>
            <Leg1Status>completed</Leg1Status>
            <Leg2Status>completed</Leg2Status>
            <Legs>
                <Leg>
                    <Id>1</Id>
                    <OnCallDuration>21</OnCallDuration>
                </Leg>
                <Leg>
                    <Id>2</Id>
                    <OnCallDuration>8</OnCallDuration>
                </Leg>
            </Legs>
        </Details>
    </Call>
</TwilioResponse>

Description of parameters under "Details" mentioned in the above response:

Parameter Name	Value
ConversationDuration	The duration for the From and To phone numbers on call in seconds
Leg1Status	Status of the first leg of the call. Can be one of completed - The call was answered and has ended normally busy - The caller received a busy signal failed - The call could not be completed as dialled, most likely because the phone number was non-existent no-answer - The call ended without being answered canceled - The call was canceled while queued or ringing
Leg2Status	Status of the second leg of the call. Can be one of completed - The call was answered and has ended normally busy - The caller received a busy signal no-answer - The call ended without being answered failed - The call could not be completed as dialed, most likely because the phone number was non-existent canceled - The call was canceled while queued or ringing null (empty) - The call did not have a second leg
Legs	Status of individual legs of the call. Contains the following information (per leg) in an array: Id - Indicates the leg. Can be 1 or 2. OnCallDuration - Indicates the duration that this leg was on a call.

The following are few examples in which API can be requested depending on the use-case:

Calls filtered by DateCreated range with Leg-wise details and Page Size = 100

GET

https://<subdomain>/v1/Accounts/<your_sid>/Calls.json?DateCreated=gte:2019-12-03+00:00:00%3Blte:2019-12-04+00:00:00&details=true&PageSize=100

Get all Incoming calls received by an agent (To number) for a given date range

GET

https://<subdomain>/v1/Accounts/<your_sid>/Calls.json?DateCreated=gte:2019-12-03+00:00:00%3Blte:2019-12-04+00:00:00&To=%2B91xxxxxxxxxx

Calls with Duration greater than 10 seconds and less than 60 seconds

GET

https://<subdomain>/v1/Accounts/<your_sid>/Calls.json?DateCreated=gte:2019-12-03+00:00:00%3Blte:2019-12-04+00:00:00&Duration=gte:11s%3Blte:59s

Calls which are failed and having ExoPhone (Virtual Phone Number) as +91xxxxxxxxxx

GET

https://<subdomain>/v1/Accounts/<your_sid>/Calls.json?DateCreated=gte:2019-12-03+00:00:00%3Blte:2019-12-04+00:00:00&Status=failed&PhoneNumber=%2B91xxxxxxxxxx

Voice

SMS

Exophones

Heartbeat

Call Campaigns

SMS Campaigns

Lead Assist

Users

ExoVerify

Whatsapp

URL shortening

More...

Voice

SMS

Exophones

Heartbeat

Call Campaigns

SMS Campaigns

LeadAssist

More...

Greeting

Connect

Passthru

Transfer

SMS

Email

More