لوكلاء AI: ملف markdown لهذه الصفحة — /docs-content-en/workday/time-control-reports.md فهرس التوثيق — /llms.txt

مقالات التوثيق متاحة حاليًا باللغة الإنجليزية فقط.

Get the monthly absence report

GET /v1/workday/time-control/reports

Returns an employee's monthly time-control report: workdays, time worked, and absences with explanations. Call it to find an absence and explain it, or to check how much an employee worked in a month.

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. Access to reports depends on the role and the time-control settings: an administrator and an employee with the full report get the report of any employee, a department head gets the reports of employees in their departments, and an employee with the simple report gets only their own. The reportViewType field on the Get time-control report settings page shows which reports are available to the credential owner. While time control is switched off, an employee without subordinates gets 403 BITRIX_ACCESS_DENIED even for their own report. READONLY keys can read the report.

Parameters

Parameter Type Required Default Description
ParameteruserId (query) Typeinteger Requiredyes Default— DescriptionEmployee ID, a positive integer. Your own ID is the userId field in the time-control report settings; IDs of department employees come from GET /v1/workday/time-control/users
Parametermonth (query) Typeinteger Requiredyes Default— DescriptionMonth, from 1 to 12
Parameteryear (query) Typeinteger Requiredyes Default— DescriptionYear, a positive integer
ParameteridleMinutes (query) Typenumber Requiredno DefaultminimumIdleForReport from the settings DescriptionMinimum break length, in minutes, for a break to count as an absence. Honored in a request from a department head or an administrator, ignored in an employee's request
ParameterworkdayHours (query) Typenumber Requiredno Default8 DescriptionWorkday length in hours; undertime and overtime are calculated from it

Examples

curl — personal key

Terminal 
curl "https://vibecode.bitrix24.com/v1/workday/time-control/reports?userId=503&month=5&year=2026" \
  -H "X-Api-Key: YOUR_API_KEY"

curl — OAuth application

Terminal 
curl "https://vibecode.bitrix24.com/v1/workday/time-control/reports?userId=503&month=5&year=2026" \
  -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/reports?userId=503&month=5&year=2026', {
  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/reports?userId=503&month=5&year=2026', {
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
  },
})
const { data } = await res.json()

Response fields

Dates are returned in ISO 8601 format with a time zone, durations in seconds.

Field Type Description
Fieldsuccess Typeboolean Descriptiontrue when the request succeeds
Fielddata.report Typeobject DescriptionReport for the month
Fielddata.report.monthTitle Typestring DescriptionMonth name
Fielddata.report.dateStart Typestring DescriptionStart of the month
Fielddata.report.dateFinish Typestring DescriptionEnd of the month
Fielddata.report.days Typearray DescriptionDays on which the employee opened a workday. For an existing employee, an empty array means there is no time-tracking data for the month: the employee did not open a workday, or time control is not set up in the Bitrix24 account. To check, see the active field in the time-control settings
Fielddata.report.days[].index Typestring DescriptionDate in YYYYMMDD format
Fielddata.report.days[].dayTitle Typestring DescriptionDate in the Bitrix24 account's date format
Fielddata.report.days[].workdayDateStart Typestring DescriptionWorkday start
Fielddata.report.days[].workdayDateFinish Typestring DescriptionWorkday end. If the day is still open, this is the time the report was built
Fielddata.report.days[].workdayComplete Typeboolean DescriptionWhether the workday is closed
Fielddata.report.days[].workdayDuration Typeinteger DescriptionWorkday duration including breaks
Fielddata.report.days[].workdayDurationFinal Typeinteger DescriptionTime worked, excluding breaks, personal absences, and unexplained absences
Fielddata.report.days[].workdayDurationConfig Typeinteger DescriptionWorkday duration according to workdayHours
Fielddata.report.days[].workdayTimeLeaksUser Typeinteger DescriptionBreaks the employee recorded themselves
Fielddata.report.days[].workdayTimeLeaksReal Typeinteger DescriptionBreaks according to automatic tracking, including personal and unexplained absences
Fielddata.report.days[].workdayTimeLeaksFinal Typeinteger DescriptionUndertime as a positive number, or overtime as a negative number
Fielddata.report.days[].reports Typearray DescriptionAbsences and events of the workday
Fielddata.report.days[].reports[].id Typestring DescriptionRecord ID. For an absence, it can be used as absenceId when explaining an absence
Fielddata.report.days[].reports[].userId Typestring DescriptionEmployee ID
Fielddata.report.days[].reports[].type Typestring DescriptionRecord type: IDLE — the employee stepped away; OFFLINE — offline; TM_START, TM_PAUSE, TM_CONTINUE, TM_END — start, pause, resumption, and end of the workday; DESKTOP_ONLINE, DESKTOP_OFFLINE, DESKTOP_START — activity of the Bitrix24 desktop app. Only a department head sees the last three types
Fielddata.report.days[].reports[].dateStart Typestring DescriptionRecord start
Fielddata.report.days[].reports[].dateFinish Typestring DescriptionRecord end. If the record is active, this is the time the report was built
Fielddata.report.days[].reports[].duration Typeinteger DescriptionRecord duration
Fielddata.report.days[].reports[].active Typeboolean DescriptionWhether the record is still ongoing
Fielddata.report.days[].reports[].entryId Typestring DescriptionID of the workday the record belongs to
Fielddata.report.days[].reports[].reportType Typestring DescriptionExplanation type: WORK — work-related, PRIVATE — personal. Any other value means there is no explanation, and the absence counts as personal
Fielddata.report.days[].reports[].reportText Typestring DescriptionExplanation text
Fielddata.report.days[].reports[].systemText Typestring | null DescriptionReason recorded by Bitrix24. Only a department head sees it
Fielddata.report.days[].reports[].sourceStart Typestring DescriptionSource of the record start: TM_EVENT — a workday action; IDLE_EVENT — the "Away" status; ONLINE_EVENT — signing in to the Bitrix24 account; OFFLINE_AGENT — switching to the "Offline" status; DESKTOP_ONLINE_EVENT, DESKTOP_START_EVENT, DESKTOP_OFFLINE_AGENT — the desktop app being turned on and off
Fielddata.report.days[].reports[].sourceFinish Typestring DescriptionSource of the record end; values as in sourceStart
Fielddata.report.days[].reports[].ipStart Typestring DescriptionIP address at the record start. Only a department head sees it
Fielddata.report.days[].reports[].ipFinish Typestring DescriptionIP address at the record end. Only a department head sees it
Fielddata.report.days[].reports[].ipStartNetwork Typeboolean | object Descriptionfalse if the IP address at the record start belongs to the office network; otherwise an object with the ip, range, and name fields — the address, the range, and the range name. Only a department head sees it
Fielddata.report.days[].reports[].ipFinishNetwork Typeboolean | object DescriptionThe same for the record end
Fielddata.user Typeobject | false DescriptionEmployee the report is built for, or false if the employee does not exist. The data.user.* fields below are returned only for an employee object
Fielddata.user.id Typeinteger DescriptionEmployee ID
Fielddata.user.active Typeboolean DescriptionWhether the employee is active
Fielddata.user.name Typestring DescriptionFirst and last name
Fielddata.user.firstName Typestring DescriptionFirst name
Fielddata.user.lastName Typestring DescriptionLast name
Fielddata.user.workPosition Typestring DescriptionPosition
Fielddata.user.avatar Typestring DescriptionProfile photo URL. An empty string if there is no photo
Fielddata.user.personalGender Typestring DescriptionGender: M or F
Fielddata.user.lastActivityDate Typestring DescriptionLast activity time in the Bitrix24 account

Response example

Response to a department head, one workday:

JSON 
{
  "success": true,
  "data": {
    "report": {
      "monthTitle": "May",
      "dateStart": "2026-05-01T00:00:00+00:00",
      "dateFinish": "2026-05-31T23:59:59+00:00",
      "days": [
        {
          "index": "20260526",
          "dayTitle": "26.05.2026",
          "workdayDateStart": "2026-05-26T09:02:11+00:00",
          "workdayDateFinish": "2026-05-26T18:05:40+00:00",
          "workdayComplete": true,
          "workdayTimeLeaksUser": 3600,
          "workdayTimeLeaksFinal": -9,
          "workdayDuration": 32609,
          "workdayDurationFinal": 28809,
          "workdayDurationConfig": 28800,
          "workdayTimeLeaksReal": 3800,
          "reports": [
            {
              "id": "153",
              "userId": "503",
              "type": "IDLE",
              "dateStart": "2026-05-26T14:10:05+00:00",
              "dateFinish": "2026-05-26T14:30:12+00:00",
              "duration": 1207,
              "active": false,
              "entryId": "2237",
              "reportType": "WORK",
              "reportText": "Client meeting",
              "systemText": null,
              "sourceStart": "IDLE_EVENT",
              "sourceFinish": "IDLE_EVENT",
              "ipStart": "203.0.113.24",
              "ipFinish": "203.0.113.24",
              "ipStartNetwork": false,
              "ipFinishNetwork": false
            }
          ]
        }
      ]
    },
    "user": {
      "id": 503,
      "active": true,
      "name": "Anna Smith",
      "firstName": "Anna",
      "lastName": "Smith",
      "workPosition": "Manager",
      "avatar": "",
      "personalGender": "F",
      "lastActivityDate": "2026-05-29T17:15:56+00:00"
    }
  }
}

Error response example

400 — a required parameter is missing or a threshold is not a number:

JSON 
{
  "success": false,
  "error": {
    "code": "INVALID_PARAMS",
    "message": "userId, month (1..12), year are required; optional thresholds must be numeric"
  }
}

Errors

HTTP Code Description
HTTP400 CodeINVALID_PARAMS DescriptionuserId, month, or year is missing or is not a positive integer, month is greater than 12, idleMinutes or workdayHours is not a number
HTTP403 CodeBITRIX_ACCESS_DENIED DescriptionThe role and time-control settings do not give the credential owner access to this employee's report: an employee with the simple report requested someone else's report, a department head without the full report requested the report of an employee outside their departments, or an employee without subordinates requested their own report while time control is switched off
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.

Known specifics

A nonexistent employee is returned without an error. For a nonexistent userId, the method returns 200: success is true, data.user is false, and data.report.days is an empty array. The indicator that the employee does not exist is data.user === false, rather than success: that field indicates a successful request, not that the employee exists. Check data.user before interpreting empty days as "there were no absences".

Employee IP addresses are personal data. The ipStart, ipFinish, ipStartNetwork, and ipFinishNetwork fields are returned only to a department head and an administrator. Store and display them according to your company's personal data processing rules.

Thresholds are rounded, and an out-of-range year is replaced with the current one. Fractional idleMinutes and workdayHours are converted to integers, and workdayHours less than 1 is treated as 1. A year less than 1900 or greater than 3000 is replaced with the current year without an error, so compare the report's dateStart with the requested month.

See also