لوكلاء AI: ملف markdown لهذه الصفحة — /docs-content-en/workday/time-control-users.md فهرس التوثيق — /llms.txt

مقالات التوثيق متاحة حاليًا باللغة الإنجليزية فقط.

List department employees

GET /v1/workday/time-control/users

Returns the list of a department's employees for time control. What the list contains depends on the credential owner's role in Bitrix24.

Requires the timeman scope. The Bitrix24 application behind an app key needs the timeman and department permissions: the method also reads the department. An administrator gets the employees of any department, a department head gets the employees of their own departments and an empty array for the others, and an employee without subordinate departments gets only themselves for any existing departmentId. The IDs in the response can be used as userId in the monthly report. READONLY keys can read the list.

Parameters

Parameter Type Required Default Description
ParameterdepartmentId (query) Typeinteger Requiredyes Default— DescriptionDepartment ID, a positive integer. List: GET /v1/departments. The departments the credential owner heads, or all departments of the Bitrix24 account for an administrator, are in the departments field on the Get time-control report settings page

Examples

curl — personal key

Terminal 
curl "https://vibecode.bitrix24.com/v1/workday/time-control/users?departmentId=12" \
  -H "X-Api-Key: YOUR_API_KEY"

curl — OAuth application

Terminal 
curl "https://vibecode.bitrix24.com/v1/workday/time-control/users?departmentId=12" \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN"

JavaScript — personal key

javascript 
const res = await fetch('https://vibecode.bitrix24.com/v1/workday/time-control/users?departmentId=12', {
  headers: {
    'X-Api-Key': 'YOUR_API_KEY',
  },
})
const { data } = await res.json()

JavaScript — OAuth application

javascript 
const res = await fetch('https://vibecode.bitrix24.com/v1/workday/time-control/users?departmentId=12', {
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
  },
})
const { data } = await res.json()

Response fields

Field Type Description
Fieldsuccess Typeboolean Descriptiontrue when the request succeeds
Fielddata Typearray DescriptionEmployees of the department itself, without nested departments, in ascending id order. A department head gets an empty array for a department they do not head. An employee without subordinate departments gets one element: themselves
Fielddata[].id Typeinteger DescriptionEmployee ID. Can be used as userId in the report on the Get the monthly absence report page
Fielddata[].name Typestring DescriptionEmployee's first and last name
Fielddata[].firstName Typestring | null DescriptionFirst name
Fielddata[].lastName Typestring | null DescriptionLast name
Fielddata[].workPosition Typestring | null DescriptionPosition
Fielddata[].avatar Typestring | null DescriptionProfile photo URL, 100×100 pixels
Fielddata[].personalGender Typestring DescriptionGender: M or F. If no gender is set in the profile, F is returned
Fielddata[].lastActivityDate Typestring | null DescriptionLast activity time in the Bitrix24 account, in ISO 8601 format with a time zone
Fielddata[].active Typeboolean DescriptionWhether the employee is active. Returned only to an employee without subordinate departments

Response example

Response to an administrator or a department head:

JSON 
{
  "success": true,
  "data": [
    {
      "id": 103,
      "name": "Anna Smith",
      "firstName": "Anna",
      "lastName": "Smith",
      "workPosition": "Manager",
      "avatar": null,
      "personalGender": "F",
      "lastActivityDate": "2026-10-07T17:08:16+00:00"
    },
    {
      "id": 105,
      "name": "John Brown",
      "firstName": "John",
      "lastName": "Brown",
      "workPosition": null,
      "avatar": null,
      "personalGender": "M",
      "lastActivityDate": null
    }
  ]
}

Response to an employee without subordinate departments — one element with the active field:

JSON 
{
  "success": true,
  "data": [
    {
      "id": 107,
      "active": true,
      "name": "Maria Lee",
      "firstName": "Maria",
      "lastName": "Lee",
      "workPosition": null,
      "avatar": null,
      "personalGender": "F",
      "lastActivityDate": "2026-10-07T20:45:08+00:00"
    }
  ]
}

Error response example

404 — no department with this departmentId:

JSON 
{
  "success": false,
  "error": {
    "code": "ENTITY_NOT_FOUND",
    "message": "Department not found"
  }
}

Errors

HTTP Code Description
HTTP400 CodeINVALID_PARAMS DescriptiondepartmentId is missing or is not a positive integer
HTTP404 CodeENTITY_NOT_FOUND DescriptionNo department with this departmentId
HTTP403 CodeBITRIX_ACCESS_DENIED DescriptionThe Bitrix24 application behind the app key lacks the department permission
HTTP409 CodeTIMEMAN_MODULE_NOT_ENABLED DescriptionTime Management is not available on this portal: the Time Management tool is switched off in the portal settings, or the module is not included in the plan
HTTP502 CodeBITRIX_UNAVAILABLE DescriptionBitrix24 is unavailable or returned a response of an unexpected shape
HTTP401 CodeMISSING_API_KEY DescriptionThe X-Api-Key header was not passed
HTTP401 CodeTOKEN_MISSING DescriptionAn app key was sent without a session token in Authorization: Bearer
HTTP401 CodeINVALID_SESSION DescriptionThe session token is invalid or has expired
HTTP403 CodeSCOPE_DENIED DescriptionThe key lacks the timeman scope
HTTP429 CodeRATE_LIMITED DescriptionThe general request limit was exceeded; the retry delay is in the Retry-After header

The full list of common API errors — Errors.

See also