×

To get details of users and devices in bulk, you will need to make a HTTP GET request to

GET

https://<your_api_key>:<your_api_token><subdomain>/v2/accounts/<your_sid>/users

  • 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 @ccm-api.exotel.com
    2. <subdomain> of Mumbai cluster is @ccm-api.in.exotel.com

<your_api_key> , <your_api_token> and <your_sid> are available in the API settings page of your Exotel Dashboard

Description of request query parameters (filters):

Parameter Name Description
fields

string; to add more fields in the GET response of the user objects.

Supported fields

  • devices : If this is set, response will contain the block that will list all the devices under the user
  • active_call : If this is set, response will indicate whether the users are on call or not
  • last_login : If this is set, response will indicate the last login status of the user

Example:
/users?fields=devices,active_call,last_login
devices.contact_uri string; Your user's device contact URI i.e. phone number in E.164 format or SIP address if VOIP is enabled. The values should be URL encoded, like + should be replaced with %2B.

Example:
/users?devices.contact_uri=+9199512131xx 
/users?devices.contact_uri=+9199512112xx,+9199512113xx
/users?devices.contact_uri=sip:1-999-123-4567@voip.exotel.com
email string; Your user's email address as added on Exotel. The values should be URL encoded.

Example:
/users?email=<email-id>
/users?email=<email-id-1>,<email-id-2>

 

curl --location --request GET 'https://<your_api_key>:<your_api_token><subdomain>/v2/accounts/<your_sid>/users?fields=devices,active_call,last_login' \


var request = require('request');
var options = {
'method': 'GET',
'url': 'https://<your_api_key>:<your_api_token><subdomain>/v2/accounts/<your_sid>/users?fields=devices,active_call,last_login',
'headers': {

}
};
request(options, function (error, response) {
if (error) throw new Error(error);
console.log(response.body);
});
<?php

$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => 'https://<your_api_key>:<your_api_token><subdomain>/v2/accounts/<your_sid>/users?fields=devices,active_call,last_login',
  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(
    
  ),
));

$response = curl_exec($curl);

curl_close($curl);
echo $response;
import requests

url = "https://<your_api_key>:<your_api_token><subdomain>/v2/accounts/<your_sid>/users?fields=devices,active_call,last_login"

payload={}
headers = {
  
}

response = requests.request("GET", url, headers=headers, data=payload)

print(response.text)
package main

import (
  "fmt"
  "net/http"
  "io/ioutil"
)

func main() {

  url := "https://<your_api_key>:<your_api_token><subdomain>/v2/accounts/<your_sid>/users?fields=devices,active_call,last_login"
  method := "GET"

  client := &http.Client {
  }
  req, err := http.NewRequest(method, url, nil)

  if err != nil {
    fmt.Println(err)
    return
  }
  req.Header.Add()

  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:

  • On success, the HTTP response status code will be 200
  • the HTTP response body will contain an JSON similar to the one below
  • Example Response
{
    "request_id": "516eecedfae14599ae1989cd528e70f0",
    "method": "GET",
    "http_code": 200,
    "metadata": {
        "total": 229,
        "count": 20,
        "offset": 0,
        "limit": 20
    },
    "response": [
        {
            "code": 200,
            "error_data": null,
            "status": "success",
            "data": {
                "active_call": "72827ead13a355d334338f53af71157s",
                "date_created": "2013-10-05T11:06:56+05:30",
                "date_updated": "2013-10-05T11:06:56+05:30",
                "devices": [
                    {
                        "id": 756,
                        "name": "My number",
                        "contact_uri": "+919XXXX47047",
                        "type": "tel",
                        "available": true,
                        "verified": true,
                        "status": "busy"
                    }
                ],
                "email": "abc@xyz.com",
                "email_verified": true,
                "first_name": "Ixxxx",
                "id": "4944735d9ae8436e91956d2ec11c638b",
                "last_name": "Syyyy",
                "last_login": "2013-09-30T09:11:20+05:30",
                "role": "admin"
            }
        },
        {
            "code": 200,
            "error_data": null,
            "status": "success",
            "data": {
                "active_call": null,
                "date_created": "2016-10-05T11:06:56+05:30",
                "date_updated": "2013-10-05T11:06:56+05:30",
                "devices": [
                    {
                        "id": 377812,
                        "name": "Primary Device",
                        "contact_uri": "+919XXXX52549",
                        "type": "tel",
                        "available": null,
                        "verified": false,
                        "status": null
                    }
                ],
                "email": "jkl@mno.com",
                "email_verified": true,
                "first_name": "Sxxxx",
                "id": "4d549a1ba55b4fab864c984963a3af91",
                "last_name": "Gyyyy",
                "last_login": "2016-09-30T09:11:20+05:30",
                "role": "admin"
            }
        }
    ]
}

Description of base parameters:

Parameter Name Type & Value
request_id This indicates the unique id of the request. Useful for debugging and tracing purposes.
method This indicates the HTTP method for the request such as GET/POST/PUT etc.
http_code This indicates the HTTP code for the request such as 200, 400, 500 etc.
metadata

This block indicates the metadata associated with the response and contains the following fields

  • total - This indicates the total number of records that are available based on the GET request and filters (if any)
  • count - This indicates the number of records returned in the response
  • offset - 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 - This indicates the maximum number of records to be returned in the response. Default limit is 20 and maximum value supported is 50 per response.
response

Response is an array of user records matching the request query. This can be set to null if there are no records present matching the request query.

Each of the element in the array contains the following

  • code - This indicates the http code for the particular record in the response array like 200, 400 etc.
  • error_data - This block will be null if there is no error else contain error information for the response with following fields
    • code - This would be the error code useful for Exotel's team to debug and can be highlighted in case of unexpected errors.
    • description - This describes the details of the error.
    • message - This is the error message corresponding to the error code useful for Exotel's team to debug and can be highlighted in case of unexpected errors.
  • status - This field would indicate status of the response (success/failure).
  • data - This block will contain the information corresponding to the response array element and will contain the fields for a user record as explained below. 

Description of parameters under each 'data' block of 'response' array:

Parameter Name Description
id User’s unique identifier. To be used as <user-id> while performing a PUT operation on the user.
first_name First name of the user
last_name Last name of the user
date_created DateTime as per ISO 8601 date format when the user was created.
Eg- 2021-07-28T02:59:34+05:30
date_updated DateTime as per ISO 8601 date format when the user was last updated.
Eg- 2021-07-28T02:59:34+05:30
last_login DateTime as per ISO 8601 date format when the agent last logged in to Exotel's Dashboard.
Eg- 2021-07-28T02:59:34+05:30
email Email ID of the user if set
email_verified Boolean (true/false); Indicates if Email ID of the user is verified or not. If verified, they can access the Exotel dashboard. Use GET call details API with the CallSid to fetch more information about the call.
active_call

CallSid of the call user is currently busy on. Eg- 72827ead13a355d334338f53af71157s

Set to null if user is not busy on a call.
role

Role of the user. Possible values:

  • admin
  • supervisor
  • user
devices

Array of devices associated with the user containing the fields as explained below.

This field is only populated if fields=devices is passed in the request

Description of parameters under each 'devices' array:

Parameter Name Description
id Unique ID of the device of the user. To be used as <device-id> while performing a PUT operation on the user.
name Friendly name of the device
contact_uri

Phone number of the device in E.164 format like +919999XXXXXX or the SIP URI of the device if it is a soft-phone like sip:arjuns2d853099.
type

Type of device. Possible values

  • sip - The device is a soft-phone with a SIP URI like sip:arjuns2d853099
  • tel - The device is a PSTN phone number like +919999XXXXXX
available

Boolean (true/false);

Indicates if the device is available (ON) i.e. true to take calls or unavailable (OFF) i.e. false. It will be set to null if device is unverified.
verified Boolean (true/false);

Indicates if the device is verified or not on Exotel. If a user needs to verify their device, these steps can be followed.
status

Indicates the current device status. Possible values-

  • busy - The device is currently busy on a call and no more calls can be dialled or received using this device.
  • free - The device is currently free and calls can be made or received on this device.

Possible error scenarios in case of this GET API - 

HttpCode Code
Description
400 1007
Request format is invalid
401 1010
Authentication failed
429 NA
Too many requests
500 1004
Internal Server Error
403 1003
API credentials used are unauthorized
403 10814
This account's KYC is incomplete. Operation not permitted
403 10815
This is a trial account. Operation not permitted

*These will be populated under the `error_data` block of response

Pagination

To fetch multiple user records information present in your account, you can utilise offset and limit parameters for pagination until response array is null.
Example: Let's assume there are 100 user records for your account. 
First request would look like below-

GET

https://<your_api_key>:<your_api_token><subdomain>/v2/accounts/<account_sid>/users?fields=devices&offset=0&limit=50

Subsequent request would be like below (and so on)-

GET

https://<your_api_key>:<your_api_token><subdomain>/v2/accounts/<account_sid>/users?fields=devices&offset=50&limit=50