## 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](/docs/workday/time-control-reports). READONLY keys can read the list.

The 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.

## Parameters

| Parameter | Type | Required | Default | Description |
|----------|-----|:-----:|-----------|----------|
| `departmentId` (query) | integer | yes | — | Department ID, a positive integer. List: [`GET /v1/departments`](/docs/entities/departments/list). 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](/docs/workday/time-control-report-settings) page |

## Examples

### curl — personal key

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

### curl — OAuth application

```bash
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 [Get the monthly absence report](/docs/workday/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 in 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 |
|------|-----|----------|
| 200 | `Warning: 299` | The filter is ignored by default; previous data is preserved and the warning is sent in the `Warning` header. |
| 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. |
| 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](/docs/errors).

## See also

- [Get the monthly absence report](/docs/workday/time-control-reports)
- [Time-control settings](/docs/workday/time-control-settings)
- [Explain an absence](/docs/workday/time-control-explain)
- [Departments](/docs/entities/departments)
- [Workday](/docs/workday)