Create User

Add a new user to your Exotel Contact Center account.

HTTP Request

POST /v2/accounts/<account_sid>/users

Request Parameters

Parameter	Required	Description
first_name	Yes	3–20 characters, alphanumeric and special chars (. ' -)
last_name	Yes	3–20 characters, alphanumeric and special chars (. ' -)
email	No	Unique valid email address
device_contact_uri	Conditional	Phone number in E.164 format
role	No	admin, supervisor, or user (default: user)
device_name	No	Friendly device identifier

Code Examples

cURL

curl -u '<api_key>:<api_token>' -X POST 'https://ccm-api.exotel.com/v2/accounts/<account_sid>/users' \
  -H 'Content-Type: application/json' \
  -d '{"first_name": "John", "last_name": "Doe", "email": "john@example.com", "device_contact_uri": "+91XXXXXXXXXX", "role": "user", "device_name": "John Mobile"}'

Python

import requests

payload = {
    'first_name': 'John',
    'last_name': 'Doe',
    'email': 'john@example.com',
    'device_contact_uri': '+91XXXXXXXXXX',
    'role': 'user',
    'device_name': 'John Mobile',
}

response = requests.post(
    'https://ccm-api.exotel.com/v2/accounts/<account_sid>/users',
    auth=('<api_key>', '<api_token>'),
    json=payload
)

print(response.status_code)
print(response.json())

Node.js

const apiKey = '<api_key>';
const apiToken = '<api_token>';

const url = 'https://ccm-api.exotel.com/v2/accounts/<account_sid>/users';

const payload = {
  first_name: 'John',
  last_name: 'Doe',
  email: 'john@example.com',
  device_contact_uri: '+91XXXXXXXXXX',
  role: 'user',
  device_name: 'John Mobile',
};

const response = await fetch(url, {
  method: 'POST',
  headers: {
    'Authorization': 'Basic ' + Buffer.from(`${apiKey}:${apiToken}`).toString('base64'),
    'Content-Type': 'application/json',
  },
  body: JSON.stringify(payload),
});

const data = await response.json();
console.log(response.status, data);

PHP

<?php
$payload = array(
    'first_name' => 'John',
    'last_name' => 'Doe',
    'email' => 'john@example.com',
    'device_contact_uri' => '+91XXXXXXXXXX',
    'role' => 'user',
    'device_name' => 'John Mobile',
);

$ch = curl_init('https://ccm-api.exotel.com/v2/accounts/<account_sid>/users');
curl_setopt($ch, CURLOPT_USERPWD, "<api_key>:<api_token>");
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'POST');
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($payload));
curl_setopt($ch, CURLOPT_HTTPHEADER, array('Content-Type: application/json'));
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

$response = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);

echo $status . "\n" . $response;
?>

Go

package main

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

func main() {
    endpoint := "https://ccm-api.exotel.com/v2/accounts/<account_sid>/users"

    payload := `{"first_name": "John", "last_name": "Doe", "email": "john@example.com", "device_contact_uri": "+91XXXXXXXXXX", "role": "user", "device_name": "John Mobile"}`

    req, err := http.NewRequest("POST", endpoint, strings.NewReader(payload))
    if err != nil {
        panic(err)
    }
    req.SetBasicAuth("<api_key>", "<api_token>")
    req.Header.Set("Content-Type", "application/json")

    res, err := http.DefaultClient.Do(req)
    if err != nil {
        panic(err)
    }
    defer res.Body.Close()

    respBody, _ := io.ReadAll(res.Body)
    fmt.Println(res.StatusCode, string(respBody))
}

Response

{
  "request_id": "string",
  "method": "POST",
  "http_code": 200,
  "response": {
    "code": 200,
    "status": "success",
    "data": {
      "id": "user_uuid",
      "first_name": "John",
      "last_name": "Doe",
      "email": "john@example.com",
      "email_verified": false,
      "role": "user",
      "devices": [
        {
          "id": 1,
          "name": "John's Phone",
          "contact_uri": "+919999999999",
          "type": "tel",
          "available": false,
          "verified": false,
          "status": null
        }
      ]
    }
  }
}

Error Codes

Code	HTTP Status	Description
1001	400	first_name is mandatory
1402	400	device_contact_uri is mandatory
1401	400	Invalid phone number format
10812	409	Device already exists
10813	409	Email conflicts with another account
10814	403	Incomplete KYC
10815	403	Trial account limitation