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

Get time-control report settings

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

Returns the credential owner's access to monthly time-control reports: their ID, role, and the departments whose reports are available to them. Call it before requesting a monthly report to find out your own ID and which employees you can access.

Requires the timeman scope. The method is available to any employee of the Bitrix24 account and describes the permissions of the user whose credentials were used for the request: for a personal key, that is the key owner; for an app key, the user whose session token is passed in Authorization. READONLY keys can read the report settings. Time-control settings for the whole Bitrix24 account are described on the Get time-control settings page.

Examples

curl — personal key

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

curl — OAuth application

Terminal 
curl "https://vibecode.bitrix24.com/v1/workday/time-control/report-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/report-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/report-settings', {
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
  },
})
const { data } = await res.json()

Response fields

Field Type Description
Fieldsuccess Typeboolean Descriptiontrue when the request succeeds
Fielddata Typeobject DescriptionThe credential owner's access to monthly reports
Fielddata.active Typeboolean DescriptionWhether time control is switched on in the Bitrix24 account. To change it: Update time-control settings
Fielddata.userId Typeinteger DescriptionCredential owner's ID. Can be used as userId in the monthly absence report when an employee requests their own report
Fielddata.userAdmin Typeboolean DescriptionWhether the credential owner is an administrator
Fielddata.userHead Typeboolean DescriptionWhether the credential owner heads at least one department
Fielddata.departments Typearray DescriptionDepartments whose reports are available to the credential owner: all departments of the Bitrix24 account for an administrator, the departments they head for a department head, an empty array for other employees
Fielddata.departments[].id Typestring DescriptionDepartment ID. Can be used as departmentId in the list of department employees
Fielddata.departments[].name Typestring DescriptionDepartment name
Fielddata.minimumIdleForReport Typeinteger DescriptionMinimum absence, in minutes, for which an employee is asked for an explanation
Fielddata.reportViewType Typestring DescriptionWhich monthly reports the credential owner sees: simple — only their own, head — reports of employees in their departments, full — reports of all employees, none — reports are not available

Response example

Response to the head of one department:

JSON 
{
  "success": true,
  "data": {
    "active": true,
    "userId": 547,
    "userAdmin": false,
    "userHead": true,
    "departments": [
      {
        "id": "9",
        "name": "Marketing and Advertising"
      }
    ],
    "minimumIdleForReport": 15,
    "reportViewType": "head"
  }
}

Error response example

403 — the key lacks the timeman scope:

JSON 
{
  "success": false,
  "error": {
    "code": "SCOPE_DENIED",
    "message": "This endpoint requires 'timeman' scope"
  }
}

Errors

HTTP Code Description
HTTP409 CodeTIMEMAN_MODULE_NOT_ENABLED DescriptionTime 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
HTTP502 CodeBITRIX_UNAVAILABLE DescriptionBitrix24 is unavailable or returned a response of an unexpected shape
HTTP401 CodeMISSING_API_KEY DescriptionThe X-Api-Key header was not passed
HTTP401 CodeTOKEN_MISSING DescriptionAn app key was sent without a session token in Authorization: Bearer
HTTP401 CodeINVALID_SESSION DescriptionThe session token is invalid or has expired
HTTP403 CodeSCOPE_DENIED DescriptionThe key lacks the timeman scope
HTTP429 CodeRATE_LIMITED DescriptionThe general request limit was exceeded; the retry delay is in the Retry-After header

The full list of common API errors — Errors.

See also