Create a User (Beta) ^Beta

This API allows you to create a new user.

POST

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

This API supports JSON response only.

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

The following are the POST parameters:

Parameter Name	Mandatory/Optional	Value
first_name	Mandatory	The first name of the user on Exotel. Following validations apply for the first name: It should consist of minimum 3 characters from uppercase letters(A-Z), lowercase letters(a-z), numbers(0-9), space after period(. ), apostrophe('), hyphen(-). The maximum number of characters allowed is 20.
last_name	Mandatory	The last name of the user on Exotel. Following validations apply for the last name: It should consist of minimum 3 characters from uppercase letters(A-Z), lowercase letters(a-z), numbers(0-9), space after period(. ), apostrophe('), hyphen(-). The maximum number of characters allowed is 20.
email	Optional	Unique and valid email ID of the user. If not set, the user will not be able to access Exotel's dashboard but calls can be made via CCM APIs provided user verifies the device.
device_contact_uri	Optional	The phone number of the user. It should be in E.164 format. For accounts where VOIP service is not enabled, this is a mandatory field For accounts where VOIP service is enabled, this is optional (SIP device will be auto created)
role	Optional	Role of the user on Exotel's dashboard. Possible values admin supervisor user Default: user (which is an agent with lowest level of access permissions) Learn more about role and access here.
device_name	Optional	User's device name. This is a friendly name to identify device.

curl --location --request POST 'https://<your_api_key>:<your_api_token><subdomain>/v2/accounts/<your_sid>/users' \
--header 'Content-Type: application/json' \
--data-raw '{
    "first_name": "Jxxxx",
    "last_name": "Ayyyy",
    "email": "abc@xyz.com",
    "device_contact_uri": "+919XXXX74572"
}'

var request = require('request');
var options = {
  'method': 'POST',
  'url': 'https://<your_api_key>:<your_api_token><subdomain>/v2/accounts/<your_sid>/users',
  'headers': {
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    "first_name": "Jxxxx",
    "last_name": "Ayyyy",
    "email": "abc@xyz.com",
    "device_contact_uri": "+919XXXX74592"
  })

};
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',
  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 =>'{
    "first_name": "Jxxxx",
    "last_name": "Ayyyy",
    "email": "abc@xyz.com",
    "device_contact_uri": "+919XXXX74572"
}',
  CURLOPT_HTTPHEADER => array(
    'Content-Type: application/json'
  ),
));

$response = curl_exec($curl);

curl_close($curl);
echo $response;

import requests
import json

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

payload = json.dumps({
  "first_name": "Jxxxx",
  "last_name": "Ayyyy",
  "email": "abc@xyz.com",
  "device_contact_uri": "+919XXXX74942"
})
headers = {
  'Content-Type': 'application/json'
}

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

print(response.text)

package main

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

func main() {

  url := "https://<your_api_key>:<your_api_token><subdomain>/v2/accounts/<your_sid>/users"
  method := "POST"

  payload := strings.NewReader(`{
    "first_name": "Jxxxx",
    "last_name": "Ayyyy",
    "email": "abc@xyz.com",
    "device_contact_uri": "+919XXXX74572"
}`)

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

  if err != nil {
    fmt.Println(err)
    return
  }
  req.Header.Add("Content-Type", "application/json")

  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 200. In case of non success message, the response body will contain the error message.
HTTP body will contain an JSON similar to the one below

Example Response
JSON

{
    "request_id": "c62ab68f25fc4f9d92eddfabe7bd155d",
    "method": "POST",
    "http_code": 200,
    "response": {
        "code": 200,
        "error_data": null,
        "status": "success",
        "data": {
            "date_created": "2021-07-21T21:43:38+05:30",
            "date_updated": "2021-07-21T21:43:38+05:30",
            "devices": [
                {
                    "id": 425215,
                    "name": "Jxxxx's device",
                    "contact_uri": "+919XXXX74572",
                    "type": "tel",
                    "available": null,
                    "verified": false,
                    "status": null
                }
            ],
            "email": "abc@xyz.com",
            "email_verified": false,
            "first_name": "Jxxxx",
            "id": "bd1fb4af48204e3fa9c22e460d2196bd",
            "last_name": "Ayyyy",
            "role": "user"
        }
    }
}

Description of response parameter:

Parameter Name	Value
request_id	This indicates the unique id of the request. Useful for debugging and tracing purpose.
method	This indicates the HTTP method for the request such as GET/POST/PUT/DELETE etc
http_code	This indicates the HTTP code for the request such as 200, 400, 500 etc.
status	failed/success
response	Response block contains the user device record matching the request URI. The block contains `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 GET/PUT/DELETE API operations on the user.
first_name	First name of the user
last_name	Last name of the user
email	Email ID of the user if set
email_verified	Boolean (true/false); Indicates if email of the user is verified or not
role	Role of the user. Possible values- admin supervisor user
devices	Array of devices associated with the user containing the fields as explained below.

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) to take calls or unavailable (OFF). 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 POST API -

HttpCode	Code	Description
400	1001	first_name is mandatory
400	1402	DeviceContactUri is mandatory
400	1401	device_contact_uri is not as per device_type
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
400	1401	Enter Valid Phone Number
400	10814	Enter valid role for user
400	1001	Email format not valid
400	1007	Invalid request body
401	1010	Authentication failed
429	NA	Too many requests
409	10812	Device already exists;Resource conflict
409	10813	Email already exists for another account;Resource conflict
500	1004	Internal Server Error

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

Update a User (Beta) ^Beta

This API allows you to update an existing user.

PUT

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

This API supports JSON response only.

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
Replace <user_id> with the user's unique identifier as present in GET user details API.

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

The following are the PUT parameters:

Parameter Name	Mandatory/Optional	Value
first_name	Optional	First name of the user. Following validations apply for the first name: It should consist of minimum 3 characters from uppercase letters(A-Z), lowercase letters(a-z), numbers(0-9), space after period(. ), apostrophe('), hyphen(-). The maximum number of characters allowed is 20.
last_name	Optional	Last name of the user. Following validations apply for the last name: It should consist of minimum 3 characters from uppercase letters(A-Z), lowercase letters(a-z), numbers(0-9), space after period(. ), apostrophe('), hyphen(-). The maximum number of characters allowed is 20.
email	Optional	This is allowed only if email wasn't configured during Create User API.

curl --location --request PUT 'https://<your_api_key>:<your_api_token><subdomain>/v2/accounts/<your_sid>/users/<user_id>' \
--header 'Content-Type: application/json' \
--data-raw '{
    "first_name":"Pxxxx"
}'

var request = require('request');
var options = {
  'method': 'PUT',
  'url': 'https://<your_api_key>:<your_api_token><subdomain>/v2/accounts/<your_sid>/users/<user_id>',
  'headers': {
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    "first_name": "Pxxxx"
  })

};
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/<user_id>',
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => '',
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 0,
  CURLOPT_FOLLOWLOCATION => true,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => 'PUT',
  CURLOPT_POSTFIELDS =>'{
    "first_name":"Pooja"
}',
  CURLOPT_HTTPHEADER => array(
    'Content-Type: application/json'
  ),
));

$response = curl_exec($curl);

curl_close($curl);
echo $response;

import requests
import json

url = "https://<your_api_key>:<your_api_token><subdomain>/v2/accounts/<your_sid>/users/<user_id>"

payload = json.dumps({
  "first_name": "Pxxxx"
})
headers = {
  'Content-Type': 'application/json'
}

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

print(response.text)

package main

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

func main() {

  url := "https://<your_api_key>:<your_api_token><subdomain>/v2/accounts/<your_sid>/users/<user_id>"
  method := "PUT"

  payload := strings.NewReader(`{
    "first_name":"Pxxxx"
}`)

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

  if err != nil {
    fmt.Println(err)
    return
  }
  req.Header.Add("Content-Type", "application/json")

  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 200. In case of non success message, the response body will contain the error message.
HTTP body will contain an JSON similar to the one below.

Example Response
JSON

{
    "request_id": "af52a0b8274a49638bbc3c711d67ceed",
    "method": "PUT",
    "http_code": 200,
    "response": {
        "code": 200,
        "error_data": null,
        "status": "success",
        "data": {
            "date_created": "2021-07-21T21:43:38+05:30",
            "date_updated": "2021-07-21T22:11:35+05:30",
            "devices": [
                {
                    "id": 425215,
                    "name": "Jxxxx's device",
                    "contact_uri": "+919XXXX74572",
                    "type": "tel",
                    "available": null,
                    "verified": false,
                    "status": null
                }
            ],
            "email": "abc@xyz.com",
            "email_verified": false,
            "first_name": "Pxxxx",
            "id": "bd1fb4af48204e3fa9c22e460d2196bd",
            "last_name": "Ayyyy",
            "role": "user"
        }
    }
}

Description of the response parameters:

Parameter Name	Value
request_id	This indicates the unique id of the request. Useful for debugging and tracing purpose
method	This indicates the HTTP method for the request such as GET/POST/PUT/DELETE etc
http_code	This indicates the HTTP code for the request such as 200, 400, 500 etc
status	failed/success
response	Response block contains the user device record matching the request URI. The block contains: `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
email	Email ID of the user
email_verified	Indicate of email of the user is verified or not
role	Role of the 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) to take calls or unavailable (OFF). 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 PUT API:

HttpCode	Code	Proposed Message
400	1002	Cannot update email
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
401	1010	Authentication failed
429	NA	Too many requests
500	1004	Internal Server Error

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

Create and Update User SIP Password ^Beta

Using this API, you will be able to reset your user's SIP password. A new password should be provided in the request. A pre-requisite for creating the SIP password is that the SIP id of the user should be created in Exotel. SIP Id is auto-generated at the time of user creation either via Create User API or during manual addition of a co-worker in the Exotel dashboard. After a successful validation of the SIP Id, the SIP password provided will be set for the user. The SIP password must contain:

1) At least 8 characters and

2) At least 3 of the following:

a) Lower case letters (a-z)

b) Upper case letters (A-Z)

c) Numbers (0-9)

d) Special characters (ex. !@#$%^&*)

To create or update a SIP password for your user, you will need to make an HTTP PUT request to

PUT

https://<your_api_key><your_api_token><subdomain>/v2/accounts/<your_sid>/users/<uuid>/devices/<device_id>/password

Example (For Singapore Stamp)-

PUT

https://<your_api_key><your_api_token>@ccm-api.exotel.com/v2/accounts/<your_sid>/users/<uuid>/devices/<device_id>/password

Example (For Mumbai Stamp)

PUT

https://<your_api_key><your_api_token>@ccm-api.in.exotel.com/v2/accounts/<your_sid>/users/<uuid>/devices/<device_id>/password

Replace <your_api_key> and <your_api_token> with the API key and token created by you OR use Basic Authentication.
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

Request Parameter Description:-

Parameter	Mandatory/Optional	Value/Description
password	Mandatory	String; New password string adhering to the password policy mentioned above

HTTP Response:

On success, the HTTP response status code will be 200

Response Parameter Description:-

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.
response	Response block contains the user device record matching the request URI. The block contains `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).

Example Response
JSON

{
  "request_id": "affd93c2e3674424993e4d70c012156e",
  "method": "PUT",
  "http_code": 200,
  "response": {
    "code": 200,
    "error_data": null,
    "status": "success",
    "data": null
  }
}

Update User Device (Beta) ^Beta

To update user's device, you will need to make a HTTP PUT request to

PUT

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

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
Replace <user_id> and <device_id> with the user's unique identifier and device identifier as present in GET user details API.

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

The following are the PUT parameters supported with Content-Type: application/json set in the header

Parameter Name

Value

available

Boolean (true/false); Indicates if the device is available (ON) to take calls or unavailable (OFF).

Example -
{
"available": true
}

NOTE: If a user has more than one device, then, only 1 device can be turned ON (set to available = true) is allowed. All other devices must be turned OFF (set to available = false) before another device can be turned ON (set to available = true).

contact_uri

The phone number of the user in E.164 format to be modified.

NOTE: Updating the contact_uri will stop routing new calls to the user to the previously configured phone number and the new contact_uri will have to be verified again.

Example -
{
"contact_uri": "+919953125068"
}

curl -X PUT \
  https://<your_api_key>:<your_api_token><subdomain>/v2/accounts/<your_sid>/users/<user_id>/devices/<device_id> \
  -H 'content-type: application/json' \
  -d '{ "available": true }'

var request = require('request');
var options = {
    url: 'https://<your_api_key>:<your_api_token><subdomain>/v2/accounts/<your_sid>/users/<user_id>/devices/<device_id>',
    method: 'PUT',
    headers: { 'content-type': 'application/json' },
    body: { available: true },
    json: true
};
function callback(error, response, body) {
    if (!error && response.statusCode == 200) {
        console.log(body);
    }
}
request(options, callback);

<?php

$request = new HttpRequest();
$request->setUrl('https://<your_api_key>:<your_api_token><subdomain>/v2/accounts/<your_sid>/users/<user_id>/devices/<device_id>');
$request->setMethod(HTTP_METH_PUT);

$request->setHeaders(array(
  'content-type' => 'application/json',
));

$request->setBody('{    
    "available": true
}
');

try {
  $response = $request->send();
  echo $response->getBody();
} catch (HttpException $ex) {
  echo $ex;
}

import requests

url = "https://<your_api_key>:<your_api_token><subdomain>/v2/accounts/<your_sid>/users/<user_id>/devices/<device_id>"

payload = "{\"available\": true}"
headers = {
    'content-type': "application/json",
    }

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

print(response.text)

require 'uri'
require 'net/http'

url = URI("https://<your_api_key>:<your_api_token><subdomain>/v2/accounts/<your_sid>/users/<user_id>/devices/<device_id>")

http = Net::HTTP.new(url.host, url.port)

request = Net::HTTP::Put.new(url)
request["content-type"] = 'application/json'
request.body = "{\"available\": true}"

response = http.request(request)
puts response.read_body

HTTP Response:

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

Example Response
JSON

{
   "request_id":"6b99d8f854244f1eb8bb91d75f1c565a",
   "method":"PUT",
   "http_code":200,
   "response": {
      "code":200,
      "error_data":null,
      "status":"success",
      "data": {
         "id":100280,
         "name":"Primary Device",
         "contact_uri":"+91917622XXXX",
         "type":"tel",
         "available":true,
         "verified":true,
         "status":"free"
      }
   }
}

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.
response	Response block contains the user device record matching the request URI. The block contains `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 'data' block:

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) to take calls or unavailable (OFF). 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 PUT API -

HttpCode	Code	Description
409	10809	This device is unverified
403	10810	Another device is ON. Only one device can be ON at a time
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
403	10817	This device is not PSTN. Operation not permitted
400	1007	device_contact_uri cannot be updated in the same request
401	1010	Authentication failed
404	10808	Device not found
404	10801	User not found
409	10811	Device already exists
429	NA	Too many requests
500	1004	Internal Server Error

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

Example - How to turn a user device ON / OFF ?

Step 1 : Fetch the user id and device id of the corresponding user where the contact_uri (phone number) is +9199512131xx by querying the GET API like below

GET

https://<your_api_key>:<your_api_token><subdomain>/v2/accounts/<account_sid>/users?fields=devices&devices.contact_uri=%2B9199512131xx

Step 2: Use the user id and device id returned in the API response to toggle the value of available by setting it to true for ON and false for OFF like below

PUT

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

curl -X PUT \
  https://<your_api_key>:<your_api_token><subdomain>/v2/accounts/<your_sid>/users/<user_id>/devices/<device_id> \
  -H 'content-type: application/json' \
  -d '{ "available": true }'

Bulk Get User & Devices Details (Beta) ^Beta

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

This API supports JSON response only.

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

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

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
JSON

{
    "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

Get User and Device Details (Beta) ^Beta

This API allows you to get a single user details along with their associated devices.

GET

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

This API supports JSON response only.

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
Replace <user_id> with the user's unique identifier as generated during Create User or present in GET Bulk user details API.

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

curl --location --request GET 'https://<your_api_key>:<your_api_token><subdomain>/v2/accounts/<your_sid>/users/<user_id>' \

var request = require('request');
var options = {
  'method': 'GET',
  'url': 'https://<your_api_key>:<your_api_token><subdomain>/v2/accounts/<your_sid>/users/<user_id>',
  '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/<user_id>',
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/<user_id>"

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/<user_id>"
  method := "GET"

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

  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))
}

HTTP Response:

Response for this request will be 200. In case of non success message, the response body will contain the error message.
HTTP body will contain an JSON similar to the one below

Example Response
JSON

{
    "request_id": "87146ab118a548b09d9c9504aad4dd69",
    "method": "GET",
    "http_code": 200,
    "response": {
        "code": 200,
        "error_data": null,
        "status": "success",
        "data": {
            "date_created": "2021-07-26T18:27:24+05:30",
            "date_updated": "2021-07-26T18:27:24+05:30",
            "email": "abc@xyz.com",
            "email_verified": false,
            "first_name": "Jxxxx",
            "id": "9f7100ea9a484b75aadefa94303f62eb",
            "last_name": "Ayyyy",
            "role": "user"
        }
    }
}

Description of response parameter:

Parameter Name	Value
request_id	This indicates the unique id of the request. Useful for debugging and tracing purpose.
method	This indicates the HTTP method for the request such as GET/POST/PUT/DELETE etc
http_code	This indicates the HTTP code for the request such as 200, 400, 500 etc.
status	failed/success
response	Response block contains the user device record matching the request URI. The block contains `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
email	Email ID of the user
email_verified	Indicate if email of the user is verified or not
role	Role of the 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) to take calls or unavailable (OFF). 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
404	10801	User not found
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

Delete a User (Beta) ^Beta

This API allows a user to be deleted by passing the user-id in the request. Once deleted this action cannot be reversed.

DELETE

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

This API supports JSON response only.

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
Replace <user_id> with the user's unique identifier as present in GET user details API.

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

curl --location --request DELETE 'https://<your_api_key>:<your_api_token><subdomain>/v2/accounts/<your_sid>/users/<user_id>'

var request = require('request');
var options = {
  'method': 'DELETE',
  'url': 'https://<your_api_key>:<your_api_token><subdomain>/v2/accounts/<your_sid>/users/<user_id>',
  '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/<user_id>',
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => '',
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 0,
  CURLOPT_FOLLOWLOCATION => true,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => 'DELETE',
  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/<user_id>"

payload = ""
headers = {}

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

print(response.text)

package main

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

func main() {

  url := "https://<your_api_key>:<your_api_token><subdomain>/v2/accounts/<your_sid>/users/<user_id>"
  method := "DELETE"

  payload := strings.NewReader(``)

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

  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))
}

HTTP Response:

Response for this request will be 200. In case of non success message, the response body will contain the error message.
HTTP body will contain an JSON similar to the one below

Example Response
JSON

{
    "request_id": "6afc1bc48dd742a6b8bb01e9be5e9761",
    "method": "DELETE",
    "http_code": 200,
    "response": {
        "code": 200,
        "error_data": null,
        "status": "success",
        "data": null
    }
}

Description of the response parameters:

Parameter Name	Value
request_id	This indicates the unique id of the request. Useful for debugging and tracing purpose.
method	This indicates the HTTP method for the request such as GET/POST/PUT/DELETE etc.
http_code	This indicates the HTTP code for the request such as 200, 400, 500 etc.
status	failed/success
response	Response block contains the user device record matching the request URI. The block contains `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.

Possible error scenarios in case of this DELETE API:

HttpCode	Code	Description
400	1007	Request format is invalid
401	1010	Authentication failed
429	NA	Too many requests
500	1004	Internal Server Error
404	10801	User not found
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

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

Create a User (Beta) ^Beta

Update a User (Beta) ^Beta

Create and Update User SIP Password ^Beta

Request Parameter Description:-

HTTP Response:

Response Parameter Description:-

Update User Device (Beta) ^Beta

Example - How to turn a user device ON / OFF ?

Bulk Get User & Devices Details (Beta) ^Beta

Pagination

Get User and Device Details (Beta) ^Beta

Delete a User (Beta) ^Beta

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

Create a User (Beta) Beta

Update a User (Beta) Beta

Create and Update User SIP Password Beta

Request Parameter Description:-

HTTP Response:

Response Parameter Description:-

Update User Device (Beta) Beta

Example - How to turn a user device ON / OFF ?

Bulk Get User & Devices Details (Beta) Beta

Pagination

Get User and Device Details (Beta) Beta

Delete a User (Beta) Beta

Create a User (Beta) ^Beta

Update a User (Beta) ^Beta

Create and Update User SIP Password ^Beta

Update User Device (Beta) ^Beta

Bulk Get User & Devices Details (Beta) ^Beta

Get User and Device Details (Beta) ^Beta

Delete a User (Beta) ^Beta