Get Work Schedule timeman.schedule.get

Choose a tool for developing with an AI agent:

use Alaio Vibecode to build an app for Bitrix24 from a task description without knowing any programming language. The agent writes the code and deploys the app to a server, with no manual hosting setup
use the MCP server to develop a REST API integration in your own project. The agent refers to the official REST documentation

Scope: timeman

Who can execute the method: a user with the "View all work schedules" permission. Employees have this permission by default

The method timeman.schedule.get retrieves the work schedule by its identifier. If the schedule does not exist or id is not a number, the method returns an empty array without an error.

Method Parameters

Required parameters are marked with *

Name
type

Description

id*
integer

Identifier of the schedule.

You can find the schedule identifier in the list of schedules on the Employees > Time and Reports > Work Schedules page

Code Examples

How to Use Examples in Documentation

cURL (Webhook)

cURL (OAuth)

JS (TS)

JS (UMD)

Python

PHP

BX24.js

PHP CRest

curl -X POST \
        -H "Content-Type: application/json" \
        -H "Accept: application/json" \
        -d '{"id":1}' \
        https://**put_your_bitrix24_address**/rest/**put_your_user_id_here**/**put_your_webhook_here**/timeman.schedule.get

curl -X POST \
        -H "Content-Type: application/json" \
        -H "Accept: application/json" \
        -d '{"id":1,"auth":"**put_access_token_here**"}' \
        https://**put_your_bitrix24_address**/rest/timeman.schedule.get

// This snippet is an ES module: top-level await requires type="module" or a bundler.
        // $b24 is an already-initialized SDK instance (see the SDK "Get started" guide).
        import { Text } from '@bitrix24/b24jssdk'
        import type { B24Frame, ISODate } from '@bitrix24/b24jssdk'
        
        declare const $b24: B24Frame
        
        // Shape of the payload returned in result (match the "response handling" section of the page)
        type ScheduleGetResult = {
          ID: number
          NAME: string
          SCHEDULE_TYPE: string
          REPORT_PERIOD: string
          REPORT_PERIOD_OPTIONS: {
            START_WEEK_DAY: number
          }
          CALENDAR_ID: number
          ALLOWED_DEVICES: {
            browser: boolean
            b24time: boolean
            mobile: boolean
            mobileRecordLocation: boolean
          }
          DELETED: string
          IS_FOR_ALL_USERS: boolean
          WORKTIME_RESTRICTIONS: unknown[] | Record<string, boolean | number>
          CONTROLLED_ACTIONS: number
          UPDATED_BY: number
          DELETED_BY: number
          DELETED_AT: string
          CREATED_BY: number
          CREATED_AT: ISODate
          SHIFTS: {
            ID: number
            NAME: string
            BREAK_DURATION: number
            WORK_TIME_START: number
            WORK_TIME_END: number
            WORK_DAYS: string
            SCHEDULE_ID: number
            DELETED: boolean
          }[]
          CALENDAR: {
            ID: number
            NAME: string
            PARENT_CALENDAR_ID: number
            SYSTEM_CODE: string
            EXCLUSIONS: unknown[] | Record<string, unknown>
          }
          SCHEDULE_VIOLATION_RULES: {
            ID: number
            SCHEDULE_ID: number
            ENTITY_CODE: string
            MAX_EXACT_START: number
            MIN_EXACT_END: number
            MAX_OFFSET_START: number
            MIN_OFFSET_END: number
            RELATIVE_START_FROM: number
            RELATIVE_START_TO: number
            RELATIVE_END_FROM: number
            RELATIVE_END_TO: number
            MIN_DAY_DURATION: number
            MAX_ALLOWED_TO_EDIT_WORK_TIME: number
            MAX_WORK_TIME_LACK_FOR_PERIOD: number
            PERIOD_TIME_LACK_AGENT_ID: number
            MAX_SHIFT_START_DELAY: number
            MISSED_SHIFT_START: number
            USERS_TO_NOTIFY: {
              FIXED_START_END: string[]
              FIXED_PER_RECORD: string[]
              FIXED_EDIT_WORKTIME: string[]
              FIXED_PERIODIC: string[]
              SHIFT_DELAY: string[]
              SHIFT_MISSED_START: string[]
            }
          }
        }
        
        try {
          const response = await $b24.actions.v2.call.make<ScheduleGetResult>({
            method: 'timeman.schedule.get',
            params: {
              id: 1,
            },
            requestId: Text.getUuidRfc4122()
          })
        
          // The payload is available only on a successful response
          if (!response.isSuccess) {
            console.error(response.getErrorMessages().join('; '))
          } else {
            const result = response.getData()!.result
            console.info('Schedule:', result.ID, result.NAME, result.SCHEDULE_TYPE)
          }
        } catch (error) {
          // Thrown on transport or SDK failures (AjaxError, SdkError, etc.)
          console.error(error)
        }

<!-- Load the SDK (UMD build); it is exposed as the global B24Js -->
        <script src="https://unpkg.com/@bitrix24/b24jssdk@1/dist/umd/index.min.js"></script>
        <script>
          async function getSchedule() {
            try {
              // Initialize the SDK inside a Bitrix24 frame
              const $b24 = await B24Js.initializeB24Frame()
        
              const response = await $b24.actions.v2.call.make({
                method: 'timeman.schedule.get',
                params: {
                  id: 1,
                },
                requestId: B24Js.Text.getUuidRfc4122()
              })
        
              // The payload is available only on a successful response
              if (!response.isSuccess) {
                console.error(response.getErrorMessages().join('; '))
                return
              }
        
              const result = response.getData().result
              console.info('Schedule:', result.ID, result.NAME, result.SCHEDULE_TYPE)
            } catch (error) {
              // Thrown on transport or SDK failures (AjaxError, SdkError, etc.)
              console.error(error)
            }
          }
        
          document.addEventListener('DOMContentLoaded', getSchedule)
        </script>

from b24pysdk.errors import BitrixAPIError, BitrixSDKException
        
        try:
            bitrix_response = client.timeman.schedule.get(bitrix_id=1).response
            result = bitrix_response.result
            print(result)
        except BitrixAPIError as error:
            print(
                "Bitrix API error",
                f"error: {error.error}",
                f"error_description: {error.error_description}",
                sep="\n",
            )
        except BitrixSDKException as error:
            print(f"Bitrix SDK error: {error.message}")
        except Exception as error:
            print(f"Unexpected error: {error}")

try {
            $response = $b24Service
                ->core
                ->call(
                    'timeman.schedule.get',
                    [
                        'id' => 1
                    ]
                );
        
            $result = $response
                ->getResponseData()
                ->getResult();
        
            print_r($result);
        } catch (Throwable $e) {
            echo $e->getMessage();
        }

BX24.callMethod(
            "timeman.schedule.get",
            {
                id: 1
            },
            function(result)
            {
                if(result.error())
                    console.error(result.error());
                else
                {
                    console.dir(result.data());
                    if(result.more())
                        result.next();
                }
            }
        );

require_once('crest.php');
        
        $result = CRest::call(
            'timeman.schedule.get',
            [
                'id' => 1
            ]
        );
        
        echo '<PRE>';
        print_r($result);
        echo '</PRE>';

// client and ctx are already created — see the Go SDK section
        res, err := client.Core().Call(ctx, "timeman.schedule.get", b24.Params{
        	"id": 1,
        }, b24.WithIdempotent())
        if err != nil {
        	return fmt.Errorf("timeman.schedule.get: %w", err)
        }
        
        var item struct {
        	ID           b24.ID `json:"ID"`
        	Name         string `json:"NAME"`
        	ScheduleType string `json:"SCHEDULE_TYPE"`
        	ReportPeriod string `json:"REPORT_PERIOD"`
        	CalendarID   b24.ID `json:"CALENDAR_ID"`
        	Deleted      string `json:"DELETED"`
        }
        if err := json.Unmarshal(res.Result, &item); err != nil {
        	return fmt.Errorf("parse response: %w", err)
        }
        fmt.Println(item.ID, item.Name)

Response Handling

HTTP Status: 200

{
            "result": {
                "ID": 1,
                "NAME": "For all employees",
                "SCHEDULE_TYPE": "FIXED",
                "REPORT_PERIOD": "MONTH",
                "REPORT_PERIOD_OPTIONS": {
                    "START_WEEK_DAY": 0
                },
                "CALENDAR_ID": 1,
                "ALLOWED_DEVICES": {
                    "browser": true,
                    "b24time": true,
                    "mobile": true,
                    "mobileRecordLocation": false
                },
                "DELETED": "0",
                "IS_FOR_ALL_USERS": true,
                "WORKTIME_RESTRICTIONS": [],
                "CONTROLLED_ACTIONS": 3,
                "UPDATED_BY": 503,
                "DELETED_BY": 0,
                "DELETED_AT": "",
                "CREATED_BY": 0,
                "CREATED_AT": "2019-09-19T21:22:22+02:00",
                "SHIFTS": [
                    {
                        "ID": 1,
                        "NAME": "",
                        "BREAK_DURATION": 3600,
                        "WORK_TIME_START": 28800,
                        "WORK_TIME_END": 61200,
                        "WORK_DAYS": "12345",
                        "SCHEDULE_ID": 1,
                        "DELETED": false
                    }
                ],
                "CALENDAR": {
                    "ID": 1,
                    "NAME": "",
                    "PARENT_CALENDAR_ID": 0,
                    "SYSTEM_CODE": "",
                    "EXCLUSIONS": []
                },
                "SCHEDULE_VIOLATION_RULES": {
                    "ID": 1,
                    "SCHEDULE_ID": 1,
                    "ENTITY_CODE": "UA",
                    "MAX_EXACT_START": 28859,
                    "MIN_EXACT_END": 61200,
                    "MAX_OFFSET_START": -1,
                    "MIN_OFFSET_END": -1,
                    "RELATIVE_START_FROM": -1,
                    "RELATIVE_START_TO": -1,
                    "RELATIVE_END_FROM": -1,
                    "RELATIVE_END_TO": -1,
                    "MIN_DAY_DURATION": 28800,
                    "MAX_ALLOWED_TO_EDIT_WORK_TIME": 300,
                    "MAX_WORK_TIME_LACK_FOR_PERIOD": 3600,
                    "PERIOD_TIME_LACK_AGENT_ID": 309429,
                    "MAX_SHIFT_START_DELAY": -1,
                    "MISSED_SHIFT_START": 0,
                    "USERS_TO_NOTIFY": {
                        "FIXED_START_END": [
                            "U503"
                        ],
                        "FIXED_PER_RECORD": [
                            "U503"
                        ],
                        "FIXED_EDIT_WORKTIME": [
                            "U503"
                        ],
                        "FIXED_PERIODIC": [
                            "U503"
                        ],
                        "SHIFT_DELAY": [],
                        "SHIFT_MISSED_START": []
                    }
                }
            },
            "time": {
                "start": 1744036659.2339499,
                "finish": 1744036659.2655749,
                "duration": 0.031625032424926758,
                "processing": 0.008758068084716797,
                "date_start": "2025-04-07T17:37:39+02:00",
                "date_finish": "2025-04-07T17:37:39+02:00",
                "operating_reset_at": 1744037259,
                "operating": 0
            }
        }

Returned Data

Name `type`	Description
result `object` \| `array`	Root element of the response. Contains an object with the description of the employees' work schedule. If a schedule with this identifier does not exist or has been deleted, the method returns an empty array
ID `integer`	Identifier of the work schedule
NAME `string`	Name of the work schedule
SCHEDULE_TYPE `string`	Type of the work schedule. Possible values: `FIXED` — fixed `SHIFT` — shift-based `FLEXTIME` — flexible
REPORT_PERIOD `string`	Frequency of report generation for the schedule. Possible values: `MONTH` — month `WEEK` — week `TWO_WEEKS` — two weeks `QUARTER` — quarter
REPORT_PERIOD_OPTIONS `object`	Object with the description of additional settings for report generation period. The field is returned for any `REPORT_PERIOD` value, and its settings apply to the `WEEK` and `TWO_WEEKS` periods
CALENDAR_ID `integer`	Identifier of the calendar associated with the work schedule
ALLOWED_DEVICES `object`	Object with the description of allowed devices for time tracking
DELETED `string`	Flag indicating if the work schedule is deleted. Always `"0"`: the method does not return a deleted schedule and returns an empty array instead
IS_FOR_ALL_USERS `boolean`	Applicability of the schedule to all employees. Value `true` means the schedule applies to all users of the system
WORKTIME_RESTRICTIONS `array` \| `object`	Work time restrictions. If there are no restrictions, an empty array is returned. If they are set, an object with the `ALLOWED_TO_EDIT_RECORD`, `ALLOWED_TO_REOPEN_RECORD`, and `MAX_SHIFT_START_OFFSET` keys is returned
CONTROLLED_ACTIONS `integer`	Employee actions controlled by the schedule. Possible values: `1` — start of the workday `2` — end of the workday `3` — start and end
UPDATED_BY `integer`	Identifier of the user who last updated the work schedule
DELETED_BY `integer`	Identifier of the user who deleted the work schedule. Value `0` indicates that the schedule has not been deleted
DELETED_AT `string`	Date and time of deletion of the work schedule. An empty string means that the schedule has not been deleted
CREATED_BY `integer`	Identifier of the user who created the work schedule. Value `0` indicates system creation
CREATED_AT `datetime`	Date and time of creation of the work schedule
SHIFTS `array`	Array of shift objects. Each object contains a description of the shift associated with the work schedule
CALENDAR `object`	Object with information about the calendar associated with the work schedule
SCHEDULE_VIOLATION_RULES `object`	Object with the description of schedule violation rules
USER_ASSIGNMENTS `DEPARTMENT_ASSIGNMENTS` `array`	Schedule assignments to employees and departments. The fields are returned only if the schedule has assignments. An employee assignment element: `SCHEDULE_ID`, `USER_ID`, `STATUS`
time `time`	Information about the request execution time

The method returns employee assignments in the DEPARTMENT_ASSIGNMENTS field and department assignments in USER_ASSIGNMENTS.

Object REPORT_PERIOD_OPTIONS

Name
type

Description

START_WEEK_DAY
integer

Day the week starts.

Possible values:

0 — Monday
1 — Tuesday
2 — Wednesday
3 — Thursday
4 — Friday
5 — Saturday
6 — Sunday

Object ALLOWED_DEVICES

Name `type`	Description
browser `boolean`	Is time tracking allowed through the browser. If `true` — tracking is allowed
b24time `boolean`	Whether time tracking through the Bitrix24.Time app is allowed
mobile `boolean`	Whether time tracking through the mobile app is allowed
mobileRecordLocation `boolean`	Whether to record the location when tracking time through the mobile app

Object SHIFTS

Name `type`	Description
ID `integer`	Identifier of the shift
NAME `string`	Name of the shift
BREAK_DURATION `integer`	Duration of the break in seconds
WORK_TIME_START `integer`	Start time of the workday in seconds from midnight
WORK_TIME_END `integer`	End time of the workday in seconds from midnight
WORK_DAYS `string`	String with codes of workdays. For example, `12345` — from Monday to Friday
SCHEDULE_ID `integer`	Identifier of the work schedule
DELETED `boolean`	Flag indicating if the shift is deleted. Value `true` means the shift is deleted

Object CALENDAR

Name `type`	Description
ID `integer`	Identifier of the calendar
NAME `string`	Name of the calendar
PARENT_CALENDAR_ID `integer`	Identifier of the parent calendar. Value `0` indicates that there is no parent calendar
SYSTEM_CODE `string`	System code of the calendar
EXCLUSIONS `array` \| `object`	Exclusions from the calendar. If there are no exclusions, an empty array is returned. If they are set, an object is returned: the key is the year, the value is the dates excluded from the calendar

Object SCHEDULE_VIOLATION_RULES

Name `type`	Description
ID `integer`	Identifier of the schedule violation rules
SCHEDULE_ID `integer`	Identifier of the work schedule
ENTITY_CODE `string`	Code of the employees to whom the rules apply. For example, `UA` — all employees
MAX_EXACT_START `integer`	Maximum exact start time of the workday in seconds from midnight
MIN_EXACT_END `integer`	Minimum exact end time of the workday in seconds from midnight
MAX_OFFSET_START `integer`	Maximum offset for the start of the workday. Value `-1` means no restriction is set
MIN_OFFSET_END `integer`	Minimum offset for the end of the workday. Value `-1` means no restriction is set
RELATIVE_START_FROM `integer`	Relative start of the workday (relative to the planned time). Value `-1` means no restriction is set
RELATIVE_START_TO `integer`	Relative end of the workday (relative to the planned time). Value `-1` means no restriction is set
RELATIVE_END_FROM `integer`	Relative start of the end of the workday. Value `-1` means no restriction is set
RELATIVE_END_TO `integer`	Relative end of the workday. Value `-1` means no restriction is set
MIN_DAY_DURATION `integer`	Minimum duration of the workday in seconds
MAX_ALLOWED_TO_EDIT_WORK_TIME `integer`	Maximum time allowed to edit work time in seconds
MAX_WORK_TIME_LACK_FOR_PERIOD `integer`	Maximum time of underwork for the period in seconds
PERIOD_TIME_LACK_AGENT_ID `integer`	Identifier of the agent checking underwork for the period
MAX_SHIFT_START_DELAY `integer`	Maximum delay for the start of the shift in seconds. Value `-1` means no restriction is set
MISSED_SHIFT_START `integer`	Whether monitoring of missed shift starts is enabled: `0` — disabled, a value greater than `0` — enabled
USERS_TO_NOTIFY `object`	Object with the description of users for notifying about schedule violations

Object USERS_TO_NOTIFY

Name `type`	Description
FIXED_START_END `array`	List of users to notify about fixed start and end of the workday. Each element of the array contains the user identifier in the format `U<ID>`
FIXED_PER_RECORD `array`	List of users to notify about fixed time records. Each element of the array contains the user identifier in the format `U<ID>`
FIXED_EDIT_WORKTIME `array`	List of users to notify about changes in work time. Each element of the array contains the user identifier in the format `U<ID>`
FIXED_PERIODIC `array`	List of users to notify about periodic schedule violations. Each element of the array contains the user identifier in the format `U<ID>`
SHIFT_DELAY `array`	List of users to notify about delays in the start of the shift
SHIFT_MISSED_START `array`	List of users to notify about missed starts of the shift

Error Handling

HTTP status: 400

{
            "error": "TIMEMAN_TOOL_DISABLED",
            "error_description": "Time management is disabled."
        }

Name `type`	Description
error `string`	String error code. It consists of digits, Latin letters, and underscores. It may arrive empty — in that case only `error_description` shows the reason
error_description `string`	Error message for the developer. Do not show it to the end user without processing

Possible Error Codes

Code	Description	Value
`TIMEMAN_TOOL_DISABLED`	Time management is disabled.	The time tracking tool is disabled
`100`	Could not find value for parameter	The required parameter `id` is not passed

Statuses and System Error Codes

HTTP Status: 4xx, 5xx

The errors described below are returned by the REST API itself, not by the logic of a specific method. They can arrive in response to any method.

Status	Code Error Message	Description
`500`	`INTERNAL_SERVER_ERROR` Internal server error	An internal server error has occurred. Retry the call, and if the error persists, contact the server administrator or Bitrix24 technical support
`500`	`ERROR_UNEXPECTED_ANSWER` Server returned an unexpected response	The server returned an unexpected response. Retry the call, and if the error persists, contact the server administrator or Bitrix24 technical support
`503`	`QUERY_LIMIT_EXCEEDED` Too many requests	The request intensity limit has been exceeded
`429`	`OPERATION_TIME_LIMIT` Method is blocked due to operation time limit	The method is blocked because the request resource intensity limit has been exceeded. The block is lifted automatically once the accumulated execution time of the method no longer exceeds the limit
`401`	`NO_AUTH_FOUND` Wrong authorization data	The request contains no authorization data: neither an access token nor a webhook code was passed
`401`	`INVALID_REQUEST` Https required	Methods are called over the HTTPS protocol only
`401`	`OVERLOAD_LIMIT` REST API is blocked due to overload	The REST API is blocked due to overload. This is a manual individual block. To have it lifted, contact Bitrix24 technical support
`401`	`ACCESS_DENIED` REST is available only on commercial plans	REST API access is not active for this account. In Bitrix24 Cloud, check the current plan or trial status: Vibe+ plans include REST API access, while Essentials plans do not. A webhook receives a different error message — `REST is available only by subscription`
`401`	`INVALID_CREDENTIALS` Invalid request credentials	No active webhook with the specified user identifier and secret code was found
`404`	`ERROR_METHOD_NOT_FOUND` Method not found!	No method with this name was found. The name is misspelled, the method does not exist in the REST API, or it is unavailable without the required scope
`401`	`insufficient_scope` The request requires higher privileges than provided by the webhook token	The request requires broader permissions than the token has: for a webhook these are the permissions granted to it, for an application it is the scope. For an application, the error message ends with `provided by the access token`
`401`	`expired_token` The access token provided has expired	The access token has expired
`401`	`user_access_error` The user does not have access to the application	The application is installed, but the Bitrix24 administrator has granted access to it only to specific users
`403`	`PORTAL_DELETED` Portal was deleted	The public part of the site is closed. To open it on an on-premise installation, disable the "Temporary closure of the public part of the site" option. Path to the setting: Desktop > Settings > Product Settings > Module Settings > Main Module > Temporary closure of the public part of the site

Continue Learning

Work Schedule: Overview of Methods

Was the article helpful?

Overview of Methods

Get Work Schedule timeman.schedule.get

Method ParametersMethod Parameters

Code ExamplesCode Examples

Response HandlingResponse Handling

Returned DataReturned Data

Object REPORT_PERIOD_OPTIONSObject REPORT_PERIOD_OPTIONS

Object ALLOWED_DEVICESObject ALLOWED_DEVICES

Object SHIFTSObject SHIFTS

Object CALENDARObject CALENDAR

Object SCHEDULE_VIOLATION_RULESObject SCHEDULE_VIOLATION_RULES

Object USERS_TO_NOTIFYObject USERS_TO_NOTIFY

Error HandlingError Handling

Possible Error CodesPossible Error Codes

Statuses and System Error CodesStatuses and System Error Codes

Continue LearningContinue Learning