[{"data":1,"prerenderedAt":7},["ShallowReactive",2],{"docs-workday\u002Ftime-control-users":3,"docs-tabs-workday\u002Ftime-control-users":6},{"content":4,"lastmod":5},"## List department employees\n\n`GET \u002Fv1\u002Fworkday\u002Ftime-control\u002Fusers`\n\nReturns the list of a department's employees for time control. What the list contains depends on the credential owner's role in Bitrix24.\n\nRequires 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](\u002Fdocs\u002Fworkday\u002Ftime-control-reports). READONLY keys can read the list.\n\nThe generic `filter` parameter is not applied by this endpoint. By default, the API preserves the previous HTTP 200 response and data, adds `Warning: 299 - \"filter is not supported on this endpoint and was ignored\"`, and records unsupported-filter use in the server log.\n\n## Parameters\n\n| Parameter | Type | Required | Default | Description |\n|----------|-----|:-----:|-----------|----------|\n| `departmentId` (query) | integer | yes | — | Department ID, a positive integer. List: [`GET \u002Fv1\u002Fdepartments`](\u002Fdocs\u002Fentities\u002Fdepartments\u002Flist). 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](\u002Fdocs\u002Fworkday\u002Ftime-control-report-settings) page |\n\n## Examples\n\n### curl — personal key\n\n```bash\ncurl \"https:\u002F\u002Fvibecode.bitrix24.com\u002Fv1\u002Fworkday\u002Ftime-control\u002Fusers?departmentId=12\" \\\n  -H \"X-Api-Key: YOUR_API_KEY\"\n```\n\n### curl — OAuth application\n\n```bash\ncurl \"https:\u002F\u002Fvibecode.bitrix24.com\u002Fv1\u002Fworkday\u002Ftime-control\u002Fusers?departmentId=12\" \\\n  -H \"X-Api-Key: YOUR_APP_KEY\" \\\n  -H \"Authorization: Bearer USER_SESSION_TOKEN\"\n```\n\n### JavaScript — personal key\n\n```javascript\nconst res = await fetch('https:\u002F\u002Fvibecode.bitrix24.com\u002Fv1\u002Fworkday\u002Ftime-control\u002Fusers?departmentId=12', {\n  headers: {\n    'X-Api-Key': 'YOUR_API_KEY',\n  },\n})\nconst { data } = await res.json()\n```\n\n### JavaScript — OAuth application\n\n```javascript\nconst res = await fetch('https:\u002F\u002Fvibecode.bitrix24.com\u002Fv1\u002Fworkday\u002Ftime-control\u002Fusers?departmentId=12', {\n  headers: {\n    'X-Api-Key': 'YOUR_APP_KEY',\n    'Authorization': 'Bearer USER_SESSION_TOKEN',\n  },\n})\nconst { data } = await res.json()\n```\n\n## Response fields\n\n| Field | Type | Description |\n|------|-----|----------|\n| `success` | boolean | `true` when the request succeeds |\n| `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 |\n| `data[].id` | integer | Employee ID. Can be used as `userId` in the report on the [Get the monthly absence report](\u002Fdocs\u002Fworkday\u002Ftime-control-reports) page |\n| `data[].name` | string | Employee's first and last name |\n| `data[].firstName` | string \\| null | First name |\n| `data[].lastName` | string \\| null | Last name |\n| `data[].workPosition` | string \\| null | Position |\n| `data[].avatar` | string \\| null | Profile photo URL, 100×100 pixels |\n| `data[].personalGender` | string | Gender: `M` or `F`. If no gender is set in the profile, `F` is returned |\n| `data[].lastActivityDate` | string \\| null | Last activity time in the Bitrix24 account, in ISO 8601 format with a time zone |\n| `data[].active` | boolean | Whether the employee is active. Returned only to an employee without subordinate departments |\n\n## Response example\n\nResponse to an administrator or a department head:\n\n```json\n{\n  \"success\": true,\n  \"data\": [\n    {\n      \"id\": 103,\n      \"name\": \"Anna Smith\",\n      \"firstName\": \"Anna\",\n      \"lastName\": \"Smith\",\n      \"workPosition\": \"Manager\",\n      \"avatar\": null,\n      \"personalGender\": \"F\",\n      \"lastActivityDate\": \"2026-10-07T17:08:16+00:00\"\n    },\n    {\n      \"id\": 105,\n      \"name\": \"John Brown\",\n      \"firstName\": \"John\",\n      \"lastName\": \"Brown\",\n      \"workPosition\": null,\n      \"avatar\": null,\n      \"personalGender\": \"M\",\n      \"lastActivityDate\": null\n    }\n  ]\n}\n```\n\nResponse to an employee without subordinate departments — one element with the `active` field:\n\n```json\n{\n  \"success\": true,\n  \"data\": [\n    {\n      \"id\": 107,\n      \"active\": true,\n      \"name\": \"Maria Lee\",\n      \"firstName\": \"Maria\",\n      \"lastName\": \"Lee\",\n      \"workPosition\": null,\n      \"avatar\": null,\n      \"personalGender\": \"F\",\n      \"lastActivityDate\": \"2026-10-07T20:45:08+00:00\"\n    }\n  ]\n}\n```\n\n## Error response example\n\n404 — no department with this `departmentId`:\n\n```json\n{\n  \"success\": false,\n  \"error\": {\n    \"code\": \"ENTITY_NOT_FOUND\",\n    \"message\": \"Department not found\"\n  }\n}\n```\n\n## Errors\n\n| HTTP | Code | Description |\n|------|-----|----------|\n| 200 | `Warning: 299` | The filter is ignored by default; previous data is preserved and the warning is sent in the `Warning` header. |\n| 400 (strict mode only) | `UNSUPPORTED_FILTER` | The server mode is disabled by default; until it is enabled, the endpoint preserves HTTP 200 and the previous data. |\n| 400 | `INVALID_PARAMS` | `departmentId` is missing or is not a positive integer |\n| 404 | `ENTITY_NOT_FOUND` | No department with this `departmentId` |\n| 403 | `BITRIX_ACCESS_DENIED` | The Bitrix24 application behind the app key lacks the `department` permission |\n| 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 |\n| 502 | `BITRIX_UNAVAILABLE` | Bitrix24 is unavailable or returned a response of an unexpected shape |\n| 401 | `MISSING_API_KEY` | The `X-Api-Key` header was not passed |\n| 401 | `TOKEN_MISSING` | An app key was sent without a session token in `Authorization: Bearer` |\n| 401 | `INVALID_SESSION` | The session token is invalid or has expired |\n| 403 | `SCOPE_DENIED` | The key lacks the `timeman` scope |\n| 429 | `RATE_LIMITED` | The general request limit was exceeded; the retry delay is in the `Retry-After` header |\n\nThe full list of common API errors — [Errors](\u002Fdocs\u002Ferrors).\n\n## See also\n\n- [Get the monthly absence report](\u002Fdocs\u002Fworkday\u002Ftime-control-reports)\n- [Time-control settings](\u002Fdocs\u002Fworkday\u002Ftime-control-settings)\n- [Explain an absence](\u002Fdocs\u002Fworkday\u002Ftime-control-explain)\n- [Departments](\u002Fdocs\u002Fentities\u002Fdepartments)\n- [Workday](\u002Fdocs\u002Fworkday)\n","2026-10-23",{},1795000593398]