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.

Examples

curl — personal key

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

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

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

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.

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

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

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

Errors

Full list of common API errors — 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
• Time-control settings
• Get the monthly absence report
• List employees
• Workday