## Get time-control settings

`GET /v1/workday/time-control/settings`

Returns the time-control settings shared by all employees of the Bitrix24 account. Call it before updating the settings to read the current values.

Requires the `timeman` scope. Bitrix24 checks the credential owner's permissions: for a personal key, that is the key owner; for an app key, the user whose session token is passed in `Authorization`. A Bitrix24 account administrator can read the settings; an employee without administrator permissions gets `403 BITRIX_ACCESS_DENIED`. The Bitrix24 application behind an app key only needs the `timeman` permission. A `READONLY` key can read the settings. Updating the settings is described on the [Update time-control settings](/docs/workday/time-control-settings-update) page.

## Examples

### curl — personal key

```bash
curl "https://vibecode.bitrix24.com/v1/workday/time-control/settings" \
  -H "X-Api-Key: YOUR_API_KEY"
```

### curl — OAuth application

```bash
curl "https://vibecode.bitrix24.com/v1/workday/time-control/settings" \
  -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/settings', {
  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/settings', {
  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` on a successful request |
| `data` | object | Time-control settings shared by the entire Bitrix24 account |
| `data.active` | boolean | Whether time control is enabled. When `false`, an employee without subordinates cannot access monthly reports on the [Time-control reports](/docs/workday/time-control-reports) page, including their own |
| `data.minimumIdleForReport` | integer | Minimum absence, in minutes, for which an employee is asked for a report. At least `1` |
| `data.registerOffline` | boolean | Whether to record when an employee is offline |
| `data.registerIdle` | boolean | Whether to record when an employee is away |
| `data.registerDesktop` | boolean | Whether to record work in the Bitrix24 desktop app |
| `data.reportRequestType` | string | Who is asked for an absence report: `all` — all employees, `user` — employees listed in `reportRequestUsers`, `none` — nobody |
| `data.reportRequestUsers` | integer[] \| string[] | IDs of employees who are asked for a report. With `reportRequestType: "user"` — a list of IDs. Elements arrive as numbers or strings, depending on how the setting was saved: compare them after converting to a number. List: [List employees](/docs/entities/users/list) |
| `data.reportSimpleType` | string | Who has access to the simple report — their own monthly time-control report: `all` — all employees, `user` — employees listed in `reportSimpleUsers`. `none` never arrives in the response: that value is stored as `user` with an empty `reportSimpleUsers` |
| `data.reportSimpleUsers` | integer[] \| string[] | IDs of employees with the simple report. With `reportSimpleType: "user"` — a list of IDs; an empty array means the simple report is not assigned to any employee. With `all` — an empty array. Elements are numbers or strings, as in `reportRequestUsers`. List: [List employees](/docs/entities/users/list) |
| `data.reportFullType` | string | Who has access to the full report — the monthly reports of all employees: `all` — all employees, `user` — employees listed in `reportFullUsers`. `none` never arrives in the response: that value is stored as `user` with an empty `reportFullUsers` |
| `data.reportFullUsers` | integer[] \| string[] | IDs of employees with the full report. With `reportFullType: "user"` — a list of IDs; an empty array means the full report is not assigned to any employee. With `all` — an empty array. Elements are numbers or strings, as in `reportRequestUsers`. List: [List employees](/docs/entities/users/list) |

## Response example

```json
{
  "success": true,
  "data": {
    "active": false,
    "minimumIdleForReport": 15,
    "registerOffline": true,
    "registerIdle": true,
    "registerDesktop": true,
    "reportRequestType": "user",
    "reportRequestUsers": ["1"],
    "reportSimpleType": "all",
    "reportSimpleUsers": [],
    "reportFullType": "all",
    "reportFullUsers": []
  }
}
```

## Error response example

403 — the credential owner is not a Bitrix24 account administrator:

```json
{
  "success": false,
  "error": {
    "code": "BITRIX_ACCESS_DENIED",
    "message": "You don't have access to user this method"
  }
}
```

## Errors

| HTTP | Code | Description |
|------|-----|----------|
| 403 | `BITRIX_ACCESS_DENIED` | The credential owner is not a portal administrator |
| 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 does not have 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

- [Update time-control settings](/docs/workday/time-control-settings-update)
- [Time-control settings](/docs/workday/time-control-settings)
- [Time-control reports](/docs/workday/time-control-reports)
- [Explain an absence](/docs/workday/time-control-explain)
- [Workday](/docs/workday)