Untuk agen AI: markdown halaman ini — /docs-content-en/workday/time-control-users.md indeks dokumentasi — /llms.txt

Artikel dokumentasi saat ini tersedia dalam bahasa Inggris.

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
departmentId (query) integer yes — Department 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 of the /v1/workday/time-control/report-settings response on the Time-control reports 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
success boolean true when the request succeeds
data array Employees 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
data[].id integer Employee ID. Can be used as userId in the report on the Time-control reports page
data[].name string Employee's first and last name
data[].firstName string | null First name
data[].lastName string | null Last name
data[].workPosition string | null Position
data[].avatar string | null Profile photo URL, 100×100 pixels
data[].personalGender string Gender: M or F. If no gender is set in the profile, F is returned
data[].lastActivityDate string | null Last activity time on the Bitrix24 account in ISO 8601 format with a time zone
data[].active boolean Whether 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
400 INVALID_PARAMS departmentId is missing or is not a positive integer
404 ENTITY_NOT_FOUND No department with this departmentId
403 BITRIX_ACCESS_DENIED The Bitrix24 application behind the app key lacks the department permission
409 TIMEMAN_MODULE_NOT_ENABLED Time 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
502 BITRIX_UNAVAILABLE Bitrix24 is unavailable or returned a response of an unexpected shape
401 MISSING_API_KEY The X-Api-Key header was not passed
401 TOKEN_MISSING An app key was sent without a session token in Authorization: Bearer
401 INVALID_SESSION The session token is invalid or has expired
403 SCOPE_DENIED The key lacks the timeman scope
429 RATE_LIMITED The general request limit was exceeded; the retry delay is in the Retry-After header

The full list of common API errors — Errors.

See also