V 2.0

Employee

Description

The Employee API provides comprehensive functionality to manage employees (agents) in a system. It offers detailed capabilities for creating, updating, listing, and managing employee information including their roles, working hours, group assignments, and destination configurations. This API is essential for HR managers, administrators, and supervisors to maintain and monitor employee data in real-time.

Authentication

All endpoints require authentication using either:

Ensure that you provide the necessary authentication parameters with each request.

Authentication Methods

  1. Session ID Authentication

    • Use the ssid parameter

    • Provides a quick and simple authentication method

  2. User ID and Token Authentication

    • Requires both userId and token parameters

    • Offers more granular access control

Note: When userId and token are used, ssid should not be present in the request.

Error Codes

Employee API Specific Error Codes

Error Code Description Potential Cause Recommended Action
1000 Invalid parameters The provided parameters are incorrect or malformed Review and correct the request parameters
1014 Invalid token Authentication token is invalid or expired Re-authenticate and obtain a new token
1015 Permission denied User lacks required permissions Verify user permissions (ADD_EMPLOYEE, EDIT_EMPLOYEES, VIEW_AGENTS, etc.)
1047 Invalid request (empty body) Request body is empty or not provided Ensure request body contains required data
1501 Data already in processing A similar request is currently being processed Wait and retry the request after a short interval
1502 Invalid filter value The provided filter parameters are incorrect or malformed Review and correct the filter parameters
1503 Invalid role id The provided role ID does not exist Verify the role ID exists in your account
1504 Invalid parent Parent employee ID is invalid or not found Provide a valid parent ID or use "root"
1505 Invalid group data Group assignment data is malformed or group IDs don't exist Verify all group IDs exist in your account
1506 Employee and parent could not be same Attempting to set employee as their own parent Choose a different parent employee
1507 Invalid AgentID The provided agent/employee ID is invalid Verify the employee ID is correct
1508 Invalid status value Status value must be 0 or 1 Use 0 for inactive, 1 for active
1509 Invalid employee Employee not found or user unauthorized to access Verify employee exists and you have access
1510 Invalid destination Destination type or value is invalid Verify destination type (MOBILE, SIP, etc.) and value
1511 Working time format is invalid Working hours are not in correct format or range Use minutes from midnight (0-1439)
1512 Email already exists The email address is already registered Use a unique email address
1513 Invalid type Employee type is invalid Use valid types: "Both", "Inbound", "Outbound"
1514 Invalid mobile number Mobile number format is incorrect Provide a valid mobile number
1515 Invalid name Employee name is empty or invalid Provide a valid employee name
1516 Invalid DID number DID number format is incorrect Verify DID number format
1517 Your agentid and your loginid must be same Agent trying to modify another agent's data Agents can only modify their own data
1518 Data could not be updated Database update operation failed Try again or contact support
1519 Call password must be minimum 6 digits (update) / 8 digits (create) Call password length requirement not met Provide password meeting length requirement
1520 You must be single field update Multiple fields provided when single field expected Update only one field at a time
1521 Please provide only valid fields Request contains invalid or unknown fields Remove invalid fields from request
1522 Data could not be inserted Database insert operation failed Try again or contact support
1523 Your agent information is already added Duplicate employee creation attempt Employee already exists with this information
1524 Invalid action The requested action is not valid Verify the action parameter
1525 Invalid target agent ID Target agent ID for operation is invalid Provide a valid target agent ID
1526 Invalid ID The provided ID is invalid Verify the ID parameter
1527 Invalid type Type parameter value is invalid Use a valid type value
1528 Invalid favorite data Favorite data format is incorrect Verify favorite data structure
1529 Invalid domain Domain parameter is invalid Provide a valid domain
1530 Invalid agent timing Agent timing data is incorrect Verify timing format and values
1532 Employee limit reached Account has reached maximum employee limit Upgrade plan or deactivate unused employees
1534 PreDelete value exceeds limit of 2 PreDelete counter exceeds maximum allowed value Contact support to resolve

Additional Error Handling Guidelines

Best Practices

  1. Validate all input parameters before making a request

  2. Handle potential authentication failures gracefully

  3. Implement appropriate error handling and retry mechanisms

  4. Use the most specific authentication method for your use case

  5. Be mindful of request frequency to prevent server overload

  6. Check employee limits before creating or activating employees

  7. Ensure email uniqueness across all employees

  8. Use proper working hours format (minutes from midnight: 0-1439)

  9. Validate role and group IDs before assignment

  10. Use partial updates when modifying employee data - only send fields that need to change

  11. Monitor change logs for audit trail and compliance

  12. Test with single employee before performing bulk operations

Working Hours Format

Working hours are specified in minutes from midnight (0-1439):

Example:

{
  "MON": [
    { "from": 540, "to": 1080 }  // 9:00 AM to 6:00 PM
  ],
  "TUE": [
    { "from": 540, "to": 1080 }
  ]
}

Multiple time slots per day:

{
  "MON": [
    { "from": 0, "to": 1137 },      // 12:00 AM to 6:57 PM
    { "from": 1139, "to": 1239 },   // 6:59 PM to 8:39 PM
    { "from": 1339, "to": 1439 }    // 10:19 PM to 11:59 PM
  ]
}

Destination Types

Common destination types for employee call routing:

Type Description Example Value
MOBILE Mobile phone number "{{mobile}}"
SIP SIP endpoint/extension "sip:user@domain.com"
LANDLINE Landline phone number "0123456789"
WEBRTC WebRTC endpoint "webrtc:endpoint"

Employee Status Values

Status Value Description
Active 1 Employee is active and can receive calls
Inactive 0 Employee is inactive and cannot receive calls

Parent Hierarchy Values

Valid parent values for employee hierarchy:

Permissions Required

Different operations require different permissions:

Operation Permission
Create Employee ADD_EMPLOYEE
Update Employee EDIT_EMPLOYEES
View Employees VIEW_AGENTS or VIEW_ALL_AGENTS
Delete Employee DELETE_EMPLOYEE

Note: Permissions can be bypassed by setting forward=true in the request (admin only).

Recommendation

For a complete understanding of all possible error codes and their implications, refer to the comprehensive SarvErrors documentation.

The documentation now provides a clear, structured overview of the Employee API's error handling, authentication methods, and best practices. The error codes table includes additional context like potential causes and recommended actions to help developers better understand and resolve issues.

Profile

https://v4-api.deepcall.com/api/v2/Employee/profile

Introduction

This document provides detailed information about the Employee Profile API endpoint. It allows retrieving complete employee information including all profile details, group assignments, role information, and working hours.

Base URL

The base URL for this API endpoint is: {{domain}}/api/v2/Employee

Authentication

Authentication is required for this endpoint. It can be done in two ways:

  1. Using ssid (Session ID)
  2. Using userId and token

Note: When userId and token are used, ssid should not be present in the request.


Get Employee Profile

Endpoint

Description

The Employee Profile endpoint retrieves complete information about a specific employee by their employee ID. This includes personal details, destination configuration, role information, group assignments, working hours, and current status.

Use Cases

Request Parameters

Parameter Type Required Description
userId string Yes* User ID for authentication (*required if ssid not provided)
token string Yes* Authentication token (*required if ssid not provided)
ssid string Yes* Session ID (*required if userId/token not provided)
empId number Yes Employee ID to retrieve profile information

Request Example

With Token and UserId

{
  "userId": "{{userid}}",
  "token": "{{token}}",
  "empId": 12345
}

With SSID

{
  "ssid": "{{ssid}}",
  "empId": 12345
}

Response Details

Success Response

Status Code: 200

{
  "status": "success",
  "code": 200,
  "message": "Employee profile retrieved successfully",
  "data": {
    "empId": 12345,
    "name": "John Doe",
    "email": "john.doe@example.com",
    "mobile": "{{mobile}}",
    "address": "123 Main Street, City",
    "destinationType": "MOBILE",
    "destinationValue": "{{mobile}}",
    "roleId": "25",
    "roleName": "Senior Agent",
    "employeeType": "Both",
    "parentPath": "START,10234",
    "parentName": "Jane Smith",
    "status": 1,
    "workingHours": [
      {
        "wDays": ["MON", "TUE", "WED", "THU", "FRI"],
        "from": 540,
        "to": 1080,
        "agentId": 12345
      }
    ],
    "groupIds": [101, 102, 105],
    "groupNames": [{ "101": "Sales Team" }, { "102": "Support Team" }, { "105": "Premium Support" }],
    "cadEnabled": 1,
    "userId": "29791451",
    "isDeleted": 0,
    "preDeleted": 0,
    "allowedBusinessNumbers": [],
    "offTimeDestination": {
      "type": "",
      "destination": ""
    },
    "ipPhoneUser": "",
    "favorite": ""
  }
}

Response Field Descriptions

Field Type Description
status string Response status ("success" or "error")
code number Response code (200 for success)
message string Success message
data object Complete employee profile data
data.empId number Employee's unique identifier
data.name string Employee's full name
data.email string Employee's email address
data.mobile string Employee's mobile number
data.address string Employee's address
data.destinationType string Call routing destination type (MOBILE, SIP, LANDLINE, WEBRTC)
data.destinationValue string Call routing destination value (phone/endpoint)
data.roleId string Employee's role ID
data.roleName string Employee's role name (human-readable)
data.employeeType string Employee type (Both, Inbound, Outbound)
data.parentPath string Parent hierarchy path
data.parentName string Parent employee name
data.status number Employee status (1=Active, 0=Inactive)
data.workingHours array Working hours configuration (array of objects)
data.groupIds array Array of group IDs employee is assigned to
data.groupNames array Array of group name objects (human-readable)
data.cadEnabled number CAD (Computer Aided Dispatch) status (1=enabled, 0=disabled)
data.userId string User/Client ID who owns this employee
data.isDeleted number Deletion status (0=Not Deleted, 1=Deleted)
data.preDeleted number Pre-deletion counter
data.allowedBusinessNumbers array Array of allowed business numbers
data.offTimeDestination object Off-time destination configuration
data.ipPhoneUser string IP phone user identifier
data.favorite string Favorite configuration

Error Response Examples

Error 1: Employee ID Not Provided

Status Code: 200

{
  "status": "error",
  "message": "empId - Field cannot be empty",
  "code": 1022
}

Error 2: Invalid Employee ID Format

Status Code: 200

{
  "status": "error",
  "message": "empId - Invalid number, only integer or float are allowed",
  "code": 1026
}

Error 3: Employee Not Found

Status Code: 200

{
  "status": "error",
  "message": "Agent Data Not found",
  "code": 1531
}

Error 4: Permission Denied

Status Code: 200

{
  "status": "error",
  "message": "Permission denied",
  "code": 1015
}

Error 5: Invalid Authentication

Status Code: 200

{
  "status": "error",
  "message": "Invalid token",
  "code": 1014
}

Profile

var axios = require('axios');
var data = '{"ssid":"{{ssid}}","empId":5}';

var config = {
 method: 'post',
 url: '{{brand}}/api/v2/Employee/profile',
 headers: { 
'Content-Length': ''
 },
 data : data
};

axios(config)
.then(function (response) {
 console.log(JSON.stringify(response.data));
})
.catch(function (error) {
 console.log(error);
});
setUrl('{{brand}}/api/v2/Employee/profile');
$request->setMethod(HTTP_Request2::METHOD_POST);
$request->setConfig(array(
 'follow_redirects' => TRUE
));
$request->setHeader(array(
 'Content-Length' => ''
));
$request->setBody('{"ssid":"{{ssid}}","empId":5}');
try {
 $response = $request->send();
 if ($response->getStatus() == 200) {
echo $response->getBody();
 }
 else {
echo 'Unexpected HTTP status: ' . $response->getStatus() . ' ' .
$response->getReasonPhrase();
 }
}
catch(HTTP_Request2_Exception $e) {
 echo 'Error: ' . $e->getMessage();
}
import http.client

conn = http.client.HTTPSConnection("{{brand}}")
payload = "{\"ssid\":\"{{ssid}}\",\"empId\":5}"
headers = {
 'Content-Length': ''
}
conn.request("POST", "/api/v2/Employee/profile", payload, headers)
res = conn.getresponse()
data = res.read()
print(data.decode("utf-8"))
var client = new RestClient("{{brand}}/api/v2/Employee/profile");
client.Timeout = -1;
var request = new RestRequest(Method.POST);
var body = @"{" + "\n" +
@"    ""ssid"":""{{ssid}}""," + "\n" +
@"    ""empId"":5" + "\n" +
@"}";
request.AddParameter("text/plain", body,  ParameterType.RequestBody);
IRestResponse response = client.Execute(request);
Console.WriteLine(response.Content);
curl --location -g --request POST '{{brand}}/api/v2/Employee/profile' \
--data-raw '{
    "ssid":"{{ssid}}",
    "empId":5
}'
var request = http.Request('POST', Uri.parse('{{brand}}/api/v2/Employee/profile'));
request.body = '''{\n    "ssid":"{{ssid}}",\n    "empId":5\n}''';

http.StreamedResponse response = await request.send();

if (response.statusCode == 200) {
   print(await response.stream.bytesToString());
}
else {
   print(response.reasonPhrase);
}
package main

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

func main() {

   url := "%7B%7Bbrand%7D%7D/api/v2/Employee/profile"
   method := "POST"

   payload := strings.NewReader(`{
    "ssid":"{{ssid}}",
    "empId":5
}`)

   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))
}
POST /api/v2/Employee/profile HTTP/1.1
Host: {{brand}}
Content-Length: 40

{
    "ssid":"{{ssid}}",
    "empId":5
}
OkHttpClient client = new OkHttpClient().newBuilder()
   .build();
MediaType mediaType = MediaType.parse("text/plain");
RequestBody body = RequestBody.create(mediaType, "{\n    \"ssid\":\"{{ssid}}\",\n    \"empId\":5\n}");
Request request = new Request.Builder()
   .url("{{brand}}/api/v2/Employee/profile")
   .method("POST", body)
   .addHeader("Content-Length", "")
   .build();
Response response = client.newCall(request).execute();
var myHeaders = new Headers();
myHeaders.append("Content-Length", "");

var raw = "{\n    \"ssid\":\"{{ssid}}\",\n    \"empId\":5\n}";

var requestOptions = {
   method: 'POST',
   headers: myHeaders,
   body: raw,
   redirect: 'follow'
};

fetch("{{brand}}/api/v2/Employee/profile", requestOptions)
   .then(response => response.text())
   .then(result => console.log(result))
   .catch(error => console.log('error', error));
CURL *curl;
CURLcode res;
curl = curl_easy_init();
if(curl) {
   curl_easy_setopt(curl, CURLOPT_CUSTOMREQUEST, "POST");
   curl_easy_setopt(curl, CURLOPT_URL, "%7B%7Bbrand%7D%7D/api/v2/Employee/profile");
   curl_easy_setopt(curl, CURLOPT_FOLLOWLOCATION, 1L);
   curl_easy_setopt(curl, CURLOPT_DEFAULT_PROTOCOL, "https");
   struct curl_slist *headers = NULL;
   headers = curl_slist_append(headers, "Content-Length: ");
   curl_easy_setopt(curl, CURLOPT_HTTPHEADER, headers);
   const char *data = "{\n    \"ssid\":\"{{ssid}}\",\n    \"empId\":5\n}";
   curl_easy_setopt(curl, CURLOPT_POSTFIELDS, data);
   res = curl_easy_perform(curl);
}
curl_easy_cleanup(curl);
#import 

dispatch_semaphore_t sema = dispatch_semaphore_create(0);

NSMutableURLRequest *request = [NSMutableURLRequest requestWithURL:[NSURL URLWithString:@"%7B%7Bbrand%7D%7D/api/v2/Employee/profile"]
   cachePolicy:NSURLRequestUseProtocolCachePolicy
   timeoutInterval:10.0];
NSDictionary *headers = @{
   @"Content-Length": @""
};

[request setAllHTTPHeaderFields:headers];
NSData *postData = [[NSData alloc] initWithData:[@"{\n    \"ssid\":\"{{ssid}}\",\n    \"empId\":5\n}" dataUsingEncoding:NSUTF8StringEncoding]];
[request setHTTPBody:postData];

[request setHTTPMethod:@"POST"];

NSURLSession *session = [NSURLSession sharedSession];
NSURLSessionDataTask *dataTask = [session dataTaskWithRequest:request
completionHandler:^(NSData *data, NSURLResponse *response, NSError *error) {
   if (error) {
      NSLog(@"%@", error);
      dispatch_semaphore_signal(sema);
   } else {
      NSHTTPURLResponse *httpResponse = (NSHTTPURLResponse *) response;
      NSError *parseError = nil;
      NSDictionary *responseDictionary = [NSJSONSerialization JSONObjectWithData:data options:0 error:&parseError];
      NSLog(@"%@",responseDictionary);
      dispatch_semaphore_signal(sema);
   }
}];
[dataTask resume];
dispatch_semaphore_wait(sema, DISPATCH_TIME_FOREVER);
open Lwt
open Cohttp
open Cohttp_lwt_unix

let postData = ref "{\n    \"ssid\":\"{{ssid}}\",\n    \"empId\":5\n}";;

let reqBody = 
   let uri = Uri.of_string "%7B%7Bbrand%7D%7D/api/v2/Employee/profile" in
   let headers = Header.init ()
      |> fun h -> Header.add h "Content-Length" ""
   in
   let body = Cohttp_lwt.Body.of_string !postData in

   Client.call ~headers ~body `POST uri >>= fun (_resp, body) ->
   body |> Cohttp_lwt.Body.to_string >|= fun body -> body

let () =
   let respBody = Lwt_main.run reqBody in
   print_endline (respBody)
$headers = New-Object "System.Collections.Generic.Dictionary[[String],[String]]"
$headers.Add("Content-Length", "")

$body = "{`n    `"ssid`":`"{{ssid}}`",`n    `"empId`":5`n}"

$response = Invoke-RestMethod '{{brand}}/api/v2/Employee/profile' -Method 'POST' -Headers $headers -Body $body
$response | ConvertTo-Json
require "uri"
require "net/http"

url = URI("{{brand}}/api/v2/Employee/profile")

http = Net::HTTP.new(url.host, url.port);
request = Net::HTTP::Post.new(url)
request["Content-Length"] = ""
request.body = "{\n    \"ssid\":\"{{ssid}}\",\n    \"empId\":5\n}"

response = http.request(request)
puts response.read_body
printf '{
    "ssid":"{{ssid}}",
    "empId":5
}'| http  --follow --timeout 3600 POST '{{brand}}/api/v2/Employee/profile' \
 Content-Length:
import Foundation
#if canImport(FoundationNetworking)
import FoundationNetworking
#endif

var semaphore = DispatchSemaphore (value: 0)

let parameters = "{\n    \"ssid\":\"{{ssid}}\",\n    \"empId\":5\n}"
let postData = parameters.data(using: .utf8)

var request = URLRequest(url: URL(string: "{{brand}}/api/v2/Employee/profile")!,timeoutInterval: Double.infinity)
request.addValue("", forHTTPHeaderField: "Content-Length")

request.httpMethod = "POST"
request.httpBody = postData

let task = URLSession.shared.dataTask(with: request) { data, response, error in 
   guard let data = data else {
      print(String(describing: error))
      semaphore.signal()
      return
   }
   print(String(data: data, encoding: .utf8)!)
   semaphore.signal()
}

task.resume()
semaphore.wait()

Example Response

 [{"key":"Date"
"value":"Thu
 20 Nov 2025 05:57:21 GMT"}
{"key":"Content-Type"
"value":"application\/json; charset=utf-8"}
{"key":"Content-Length"
"value":"678"}
{"key":"Connection"
"value":"keep-alive"}
{"key":"Access-Control-Allow-Origin"
"value":"*"}
{"key":"Access-Control-Allow-Methods"
"value":"GET
 PUT
 POST
 DELETE
 OPTIONS"}
{"key":"Access-Control-Allow-Headers"
"value":"session-token
Authorization
Origin
Accept
Content-Type
DNT
Authorization
Keep-Alive
User-Agent
X-Requested-With
If-Modified-Since
Cache-Control
Content-Type
Content-Range
Range"}
{"key":"Access-Control-Allow-Credentials"
"value":"true"}
{"key":"Vary"
"value":"Origin"}
{"key":"ETag"
"value":"W\/\"2a6-d\/uvu5zCMeO4XazRktB7FmOuDDs\""}
{"key":"Strict-Transport-Security"
"value":"max-age=15724800; includeSubDomains"}
{"key":"Access-Control-Max-Age"
"value":"1728000"}]
 {
    "status": "success",
    "code": 200,
    "message": "Employee profile retrieved successfully",
    "data": {
        "name": "bhawesh",
        "favorite": "",
        "email": "brijendra11.u@{{brand}}",
        "mobile": "918442021533",
        "address": "jaipur",
        "destinationType": "MOBILE",
        "destinationValue": "8442021533",
        "roleId": "1",
        "parentPath": ",START,6,",
        "userId": "29791451",
        "empId": 5,
        "allowedBusinessNumbers": [],
        "status": 1,
        "isDeleted": 0,
        "preDeleted": 1,
        "offTimeDestination": {
            "type": "",
            "destination": ""
        },
        "employeeType": "Both",
        "ipPhoneUser": "",
        "groupIds": [
            33
        ],
        "workingHours": [
            {
                "wDays": [
                    "MON",
                    "TUE",
                    "WED",
                    "THU",
                    "FRI",
                    "SAT"
                ],
                "from": 60,
                "to": 1439,
                "agentId": 5
            }
        ],
        "groupNames": [
            {
                "33": "test double id"
            }
        ],
        "roleName": "test",
        "parentName": "Bhawna ji"
    }
}
©2021-2025 DeepCall (Powered by Sarv.com). All rights reserved.