Get Report on Identified Absences timeman.timecontrol.reports.get

Scope: timeman

Who can execute the method: any user with report viewing permission

The method timeman.timecontrol.reports.get retrieves a report on identified absences.

Method Parameters

Required parameters are marked with *

Name `type`	Description
USER_ID* `integer`	User ID for whom the reports are requested. You can obtain the user ID using the user.get method.
MONTH* `integer`	Month number
YEAR* `integer`	Year
IDLE_MINUTES `integer`	Maximum time of absence at the workplace that is not counted as absence. This parameter is available to the manager and administrator. If not specified, the time from the module settings is used.
WORKDAY_HOURS `integer`	Duration of the workday in hours. Default is 8 hours.

Code Examples

How to Use Examples in Documentation

cURL (Webhook)

cURL (OAuth)

PHP

BX24.js

PHP CRest

curl -X POST \
        -H "Content-Type: application/json" \
        -H "Accept: application/json" \
        -d '{"USER_ID":3,"MONTH":5,"YEAR":2025,"IDLE_MINUTES":15,"WORKDAY_HOURS":8}' \
        https://**put_your_bitrix24_address**/rest/**put_your_user_id_here**/**put_your_webhook_here**/timeman.timecontrol.reports.get

curl -X POST \
        -H "Content-Type: application/json" \
        -H "Accept: application/json" \
        -d '{"USER_ID":3,"MONTH":5,"YEAR":2025,"IDLE_MINUTES":15,"WORKDAY_HOURS":8,"auth":"**put_access_token_here**"}' \
        https://**put_your_bitrix24_address**/rest/timeman.timecontrol.reports.get

try
        {
        	const response = await $b24.callMethod(
        		'timeman.timecontrol.reports.get',
        		{
        			'USER_ID': 3,
        			'MONTH': 5,
        			'YEAR': 2025,
        			'IDLE_MINUTES': 15,
        			'WORKDAY_HOURS': 8
        		}
        	);
        	
        	const result = response.getData().result;
        	console.info(result);
        }
        catch( error )
        {
        	console.error(error);
        }

try {
            $response = $b24Service
                ->core
                ->call(
                    'timeman.timecontrol.reports.get',
                    [
                        'USER_ID'       => 3,
                        'MONTH'         => 5,
                        'YEAR'          => 2025,
                        'IDLE_MINUTES'  => 15,
                        'WORKDAY_HOURS' => 8
                    ]
                );
        
            $result = $response
                ->getResponseData()
                ->getResult();
        
            echo 'Success: ' . print_r($result, true);
            echo 'Info: ' . print_r($result, true);
        
        } catch (Throwable $e) {
            error_log($e->getMessage());
            echo 'Error getting time control reports: ' . $e->getMessage();
        }

BX24.callMethod(
            'timeman.timecontrol.reports.get',
            {
                'USER_ID': 3,
                'MONTH': 5,
                'YEAR': 2025,
                'IDLE_MINUTES': 15,
                'WORKDAY_HOURS': 8
            },
            function(result) {
                if (result.error()) {
                    console.error(result.error());
                } else {
                    console.info(result.data());
                }
            }
        );

require_once('crest.php');
        
        $result = CRest::call(
            'timeman.timecontrol.reports.get',
            [
                'USER_ID' => 3,
                'MONTH' => 5,
                'YEAR' => 2025,
                'IDLE_MINUTES' => 15,
                'WORKDAY_HOURS' => 8
            ]
        );
        
        echo '<PRE>';
        print_r($result);
        echo '</PRE>';

Response Handling

HTTP Status: 200

{
            "result": {
                "report": {
                    "month_title": "May",
                    "date_start": "2025-05-01T00:00:00+02:00",
                    "date_finish": "2025-05-31T23:59:59+02:00",
                    "days": [
                        {
                            "index": "20250526",
                            "day_title": "05/26/2025",
                            "workday_date_start": "2025-05-26T14:44:47+02:00",
                            "workday_date_finish": "2025-05-26T14:45:29+02:00",
                            "workday_complete": true,
                            "workday_time_leaks_user": 0,
                            "workday_time_leaks_final": 28758,
                            "workday_duration": 42,
                            "workday_duration_final": 42,
                            "workday_duration_config": 28800,
                            "reports": [
                                {
                                    "id": "27",
                                    "user_id": "503",
                                    "type": "TM_START",
                                    "date_start": "2025-05-26T14:44:47+02:00",
                                    "date_finish": "2025-05-26T14:44:47+02:00",
                                    "duration": 0,
                                    "active": false,
                                    "entry_id": "2237",
                                    "report_type": "WORK",
                                    "report_text": "Worked on the project",
                                    "system_text": null,
                                    "source_start": "TM_EVENT",
                                    "source_finish": "TM_EVENT",
                                    "ip_start": "83.219.151.30",
                                    "ip_finish": "83.219.151.30",
                                    "ip_start_network": false,
                                    "ip_finish_network": false
                                },
                                {
                                    "id": "29",
                                    ...
                                }
                            ],
                            "workday_time_leaks_real": 0
                        }
                    ]
                },
                "user": {
                    "id": 3,
                    "active": true,
                    "name": "Natalie Brooks",
                    "first_name": "Natalie",
                    "last_name": "Brooks",
                    "work_position": "IT Specialist",
                    "avatar": "http://test.bitrix24.com/upload/resize_cache/45749/7acf4ca766af5d8/main/c89/c89c6b73470635c/4R5A1256.png",
                    "personal_gender": "F",
                    "last_activity_date": "2025-05-29T17:15:56+02:00"
                },
                "time": {
                    "start": 1748528193.688745,
                    "finish": 1748528193.730104,
                    "duration": 0.04135894775390625,
                    "processing": 0.014277935028076172,
                    "date_start": "2025-05-29T17:16:33+02:00",
                    "date_finish": "2025-05-29T17:16:33+02:00",
                    "operating_reset_at": 1748528793,
                    "operating": 0
                }
            }
        }

If the response has empty days

If the method returns an empty array days, configure the time control tool.

Execute the method timeman.timecontrol.settings.set under an administrator with the following parameters:

BX24.callMethod(
            'timeman.timecontrol.settings.set',
            {
                active: true,
                REPORT_SIMPLE_TYPE: 'all',
                REPORT_FULL_TYPE: 'all',
                report_request_type: 'user',
                report_request_users: 3,
            },
            function(result){
                if(result.error())
                {
                    console.error(result.error().ex);
                }
                else
                {
                    console.log(result.data());
                }
            }
        );

Open or close the user's workday.
Execute the method timeman.timecontrol.reports.get. The response will include data in days.

Returned Data

Name `type`	Description
result `object`	Root element of the response
report `object`	Report information
month_title `string`	Month name
date_start `datetime`	Start date of the sampling period in ATOM format
date_finish `datetime`	End date of the sampling period in ATOM format
days `array`	List of objects describing worked days
user `object`	Object with information about the user
time `time`	Information about the request execution time

Objects days

Name `type`	Description
index `integer`	Weekday index in the format `YYYYMMDD`, for example, `20250526` for May 26, 2025
day_title `string`	Date in site format
workday_date_start `datetime`	Start date of the workday in ATOM format
workday_date_finish `datetime`	End date of the workday in ATOM format. If `workday_complete = false`, the date is indicated at the moment of report generation.
workday_complete `boolean`	Workday completed
workday_time_leaks_user `integer`	Duration of break in seconds
workday_time_leaks_final `integer`	Duration of time in seconds that the user underworked or overworked. Positive number — amount of underworked time in seconds Negative number — amount of time worked beyond the required time, i.e., overtime.
workday_duration `integer`	Duration of the workday according to the schedule in seconds, including breaks
workday_duration_final `integer`	Duration of the workday according to actual output in seconds. Includes: breaks unconfirmed absences absences for personal matters.
workday_duration_config `integer`	Required duration of the workday in seconds
reports `array`	List of objects with records of identified absences. Values are displayed in full detail of the report and for the manager.
workday_time_leaks_real `integer`	Duration of break established by the automatic recording system. Contains unconfirmed absences and absences for personal matters.

Objects reports

Name `type`	Description
id `string`	Record ID
user_id `string`	User ID
type `string`	Record type. Possible values: `IDLE` — stepped away, recorded using the desktop application `OFFLINE` — offline `DESKTOP_ONLINE` — launched the application. For manager only `DESKTOP_OFFLINE` — turned off the application. For manager only `DESKTOP_START` — launched the application. For manager only `TM_START` — started the workday `TM_PAUSE` — went on break `TM_CONTINUE` — continued the day `TM_END` — finished the workday
date_start `datetime`	Start date of the recording in ATOM format
date_finish `datetime`	End date of the recording in ATOM format. If `active = true`, the field contains the date at the moment of report generation.
duration `integer`	Duration
active `boolean`	Activity of the record
entry_id `string`	Time record ID
report_type `string`	Absence type. Possible values: `work` — for work matters `private` — for personal matters `none` — type not specified, equated to `private`
report_text `string`	Description of the reason for absence
system_text `string`	System description of the reason for absence. For manager only
source_start `string`	Data source for the start of the record. Possible values: `ONLINE_EVENT` — user authorization event `OFFLINE_AGENT` — agent that sets the Offline status `DESKTOP_OFFLINE_AGENT` — agent that sets the application off status `DESKTOP_ONLINE_EVENT` — event that sets the application on status `DESKTOP_START_EVENT` — event that sets the application on status `IDLE_EVENT` — event changing the status to Stepped Away. Recorded by the application `TM_EVENT` — event changing the workday: start, break, end.
source_finish `string`	Data source for the end of the record. Possible values: `ONLINE_EVENT` — user authorization event `OFFLINE_AGENT` — agent that sets the Offline status `DESKTOP_OFFLINE_AGENT` — agent that sets the application off status `DESKTOP_ONLINE_EVENT` — event that sets the application on status `DESKTOP_START_EVENT` — event that sets the application on status `IDLE_EVENT` — event changing the status to Stepped Away. Recorded by the application `TM_EVENT` — event changing the workday: start, break, end.
ip_start `string`	IP address at the start of the record. For manager only
ip_finish `string`	IP address at the end of the record. For manager only
ip_start_network `boolean` \| `object`	Object with IP address decoding for the start of the record, if the IP address is not within the office network. For office network, it will return `false`. For manager only
ip_finish_network `boolean` \| `object`	Object with IP address decoding for the end of the record, if the IP address is not within the office network. For office network, it will return `false`. For manager only

Object ip_network

Name `type`	Description
ip `string`	IP address
range `string`	Range that includes the specified IP address
name `string`	Name of the range that includes the specified IP address

Object user

Name `type`	Description
id `integer`	User ID
active `boolean`	Activity
name `string`	User's full name
first_name `string`	User's first name
last_name `string`	User's last name
work_position `string`	Position
avatar `string`	User's avatar URL. If the value is empty, the user has no avatar.
personal_gender `string`	User's gender
last_activity_date `datetime`	Date of the user's last action in ATOM format

Error Handling

HTTP Status: 400

{
            "error": "USER_ACCESS_ERROR",
            "error_description": "You don't have access to report for this user"
        }

Name `type`	Description
error `string`	String error code. It may consist of digits, Latin letters, and underscores
error_description `error_description`	Textual description of the error. The description is not intended to be shown to the end user in its raw form

Possible Error Codes

Code	Description	Value
`ACCESS_ERROR`	You don't have access to this method	You do not have access to this method
`USER_ACCESS_ERROR`	You don't have access to report for this user	You do not have access to this user's reports

Statuses and System Error Codes

HTTP Status: 20x, 40x, 50x

The errors described below may occur when calling any method.

Status	Code Error Message	Description
`500`	`INTERNAL_SERVER_ERROR` Internal server error	An internal server error has occurred, please contact the server administrator or Bitrix24 technical support
`500`	`ERROR_UNEXPECTED_ANSWER` Server returned an unexpected response	An internal server error has occurred, please contact the server administrator or Bitrix24 technical support
`503`	`QUERY_LIMIT_EXCEEDED` Too many requests	The request intensity limit has been exceeded
`405`	`ERROR_BATCH_METHOD_NOT_ALLOWED` Method is not allowed for batch usage	The current method is not allowed to be called using batch
`400`	`ERROR_BATCH_LENGTH_EXCEEDED` Max batch length exceeded	The maximum length of parameters passed to the batch method has been exceeded
`401`	`NO_AUTH_FOUND` Wrong authorization data	Invalid access token or webhook code
`400`	`INVALID_REQUEST` Https required	The methods must be called using the HTTPS protocol
`503`	`OVERLOAD_LIMIT` REST API is blocked due to overload	The REST API is blocked due to overload. This is a manual individual block, to remove it you need to contact Bitrix24 technical support
`403`	`ACCESS_DENIED` REST API is available only on commercial plans	The REST API is available only on commercial plans
`403`	`INVALID_CREDENTIALS` Invalid request credentials	The user whose access token or webhook was used to call the method lacks permissions
`404`	`ERROR_MANIFEST_IS_NOT_AVAILABLE` Manifest is not available	The manifest is not available
`403`	`insufficient_scope` The request requires higher privileges than provided by the webhook token	The request requires higher privileges than those provided by the webhook token
`401`	`expired_token` The access token provided has expired	The provided access token has expired
`403`	`user_access_error` The user does not have access to the application	The user does not have access to the application. This means that the application is installed, but the account administrator has allowed access to this application only for specific users
`500`	`PORTAL_DELETED` Portal was deleted	The public part of the site is closed. To open the public part of the site on an on-premise installation, disable the option "Temporary closure of the public part of the site". Path to the setting: Desktop > Settings > Product Settings > Module Settings > Main Module > Temporary closure of the public part of the site

Continue Learning

Submit Absence Report

Get Time Control Tool Settings

Get Report on Identified Absences timeman.timecontrol.reports.get

Method ParametersMethod Parameters

Code ExamplesCode Examples

Response HandlingResponse Handling

If the response has empty daysIf the response has empty days

Returned DataReturned Data

Objects daysObjects days

Objects reportsObjects reports

Object ip_networkObject ip_network

Object userObject user

Error HandlingError Handling

Possible Error CodesPossible Error Codes

Statuses and System Error CodesStatuses and System Error Codes

Continue LearningContinue Learning