## Update time-control settings

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

Changes the time-control settings for the entire Bitrix24 account: the passed fields are overwritten, and the rest keep their previous values.

Requires the `timeman` scope. Permissions are checked for the credential owner: 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 change the settings; an employee without administrator rights gets `403 BITRIX_ACCESS_DENIED`. The Bitrix24 application behind the app key needs only the `timeman` permission. A `READONLY` key cannot change the settings. For the current values, see [Get time-control settings](/docs/workday/time-control-settings-list).

## Request fields (body)

All fields are optional, but the body must contain at least one. The fields come in pairs: `reportRequestType` and `reportRequestUsers`, `reportSimpleType` and `reportSimpleUsers`, `reportFullType` and `reportFullUsers`. Pass the `user` type together with its list in the same request, and pass a list only together with the `user` type.

| Field | Type | Description |
|------|-----|----------|
| `active` | boolean | Switches time control on or off. With `false`, an employee without subordinates has no access to monthly reports on the [Time-control reports](/docs/workday/time-control-reports) page, including their own |
| `minimumIdleForReport` | integer | Minimum absence, in minutes, for which an employee is asked for a report. A value below `1` is saved as `1` |
| `registerOffline` | boolean | Whether to record when an employee is offline |
| `registerIdle` | boolean | Whether to record when an employee is away |
| `registerDesktop` | boolean | Whether to record work in the Bitrix24 desktop app |
| `reportRequestType` | string | Whom to ask for an absence report: `all` — all employees, `user` — employees from `reportRequestUsers`, `none` — nobody |
| `reportRequestUsers` | integer[] | IDs of the employees who are asked for a report — positive integers. An empty array is allowed. List: [List employees](/docs/entities/users/list) |
| `reportSimpleType` | string | Who has access to the simple report — their own monthly time-control report: `all` — all employees, `user` — employees from `reportSimpleUsers`, `none` — nobody. `none` is saved as `user` with an empty `reportSimpleUsers` |
| `reportSimpleUsers` | integer[] | IDs of the employees with the simple report — positive integers. An empty array is allowed. List: [List employees](/docs/entities/users/list) |
| `reportFullType` | string | Who has access to the full report — the monthly reports of all employees: `all` — all employees, `user` — employees from `reportFullUsers`, `none` — nobody. `none` is saved as `user` with an empty `reportFullUsers` |
| `reportFullUsers` | integer[] | IDs of the employees with the full report — positive integers. An empty array is allowed. List: [List employees](/docs/entities/users/list) |

## Examples

### curl — personal key

```bash
curl -X PATCH "https://vibecode.bitrix24.com/v1/workday/time-control/settings" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"reportSimpleType": "user", "reportSimpleUsers": [103, 107]}'
```

### curl — OAuth application

```bash
curl -X PATCH "https://vibecode.bitrix24.com/v1/workday/time-control/settings" \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"reportSimpleType": "user", "reportSimpleUsers": [103, 107]}'
```

### JavaScript — personal key

```javascript
const res = await fetch('https://vibecode.bitrix24.com/v1/workday/time-control/settings', {
  method: 'PATCH',
  headers: {
    'X-Api-Key': 'YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ reportSimpleType: 'user', reportSimpleUsers: [103, 107] }),
})
const { data } = await res.json()
```

### JavaScript — OAuth application

```javascript
const res = await fetch('https://vibecode.bitrix24.com/v1/workday/time-control/settings', {
  method: 'PATCH',
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ reportSimpleType: 'user', reportSimpleUsers: [103, 107] }),
})
const { data } = await res.json()
```

## Response fields

The response contains all of the account's time-control settings after the write, not only the changed fields. For a detailed description of each field, see [Get time-control settings](/docs/workday/time-control-settings-list).

| Field | Type | Description |
|------|-----|----------|
| `success` | boolean | `true` on a successful write |
| `data` | object | Time-control settings after the write |
| `data.active` | boolean | Whether time control is switched on |
| `data.minimumIdleForReport` | integer | Minimum absence, in minutes, for which a report is requested |
| `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 | `all`, `user` or `none` |
| `data.reportRequestUsers` | integer[] \| string[] | IDs of the employees who are asked for a report |
| `data.reportSimpleType` | string | `all` or `user`. If you write `none`, it comes back as `user` with an empty `reportSimpleUsers` |
| `data.reportSimpleUsers` | integer[] \| string[] | IDs of the employees with the simple report |
| `data.reportFullType` | string | `all` or `user`. If you write `none`, it comes back as `user` with an empty `reportFullUsers` |
| `data.reportFullUsers` | integer[] \| string[] | IDs of the employees with the full report |

IDs written by this method come back as numbers. IDs saved earlier by other means may come back as strings, like `reportRequestUsers` in the example below. Compare IDs after converting them to numbers.

## Response example

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

## Error response example

400 — the `reportRequestUsers` list is passed without `reportRequestType: "user"`:

```json
{
  "success": false,
  "error": {
    "code": "INVALID_PARAMS",
    "message": "reportRequestUsers requires the matching type user"
  }
}
```

## Errors

| HTTP | Code | Description |
|------|-----|----------|
| 400 | `INVALID_PARAMS` | The body is empty or not an object: `Provide at least one setting` |
| 400 | `INVALID_PARAMS` | Unknown field: `Unknown setting: <field>` |
| 400 | `INVALID_PARAMS` | Invalid value type: `active` or `register*` is not `true` or `false`, `minimumIdleForReport` is not an integer, `*Type` is not `all`, `user` or `none`, `*Users` is not an array of positive integers |
| 400 | `INVALID_PARAMS` | Type `user` is passed without its list, or a list is passed without type `user`: `reportRequestType requires the matching users array`, `reportRequestUsers requires the matching type user` |
| 403 | `BITRIX_ACCESS_DENIED` | The credential owner is not a Bitrix24 account administrator |
| 403 | `WRITE_BLOCKED_READONLY_KEY` | The key is in `READONLY` mode |
| 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 |

Full list of common API errors — [Errors](/docs/errors).

## Known specifics

- The body is validated as a whole before the write: if any field is invalid, no settings are changed, not even the valid fields from the same request.
- Employee IDs in `*Users` are not checked for existence: a nonexistent ID is saved without an error.

## See also

- [Get time-control settings](/docs/workday/time-control-settings-list)
- [Time-control settings](/docs/workday/time-control-settings)
- [Time-control reports](/docs/workday/time-control-reports)
- [List employees](/docs/entities/users/list)
- [Workday](/docs/workday)