×

    • Create a User (Beta)

    This API allows you to create a new user.

    POST

    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

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