Time-control settings

Time-control settings shared by all employees of the Bitrix24 account: whether time control is on, who is asked for an absence report, and who can access monthly reports.

Scope: timeman | Base URL: https://vibecode.bitrix24.com/v1 | Authorization: X-Api-Key

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

Examples

curl — personal key

Terminal

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

curl — OAuth application

Terminal

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

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: