For AI agents: markdown of this page — /docs-content-en/workday/time-control-settings-update.md documentation index — /llms.txt

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.

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 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
`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
`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

Examples

curl — personal key

Terminal

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

Terminal

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.

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":