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

Work schedule

GET /v1/workday/schedule

Returns a work schedule by identifier. The id parameter is required. If a schedule with the given identifier does not exist, an empty array is returned.

Parameters

Parameter In Type Req. Default Description
id query number yes — Schedule identifier. The list of schedules and their identifiers is configured in the work time tracking section of your Bitrix24 account

Examples

curl — personal key

Terminal 
curl -H "X-Api-Key: YOUR_API_KEY" \
  "https://vibecode.bitrix24.com/v1/workday/schedule?id=1"

curl — OAuth application

Terminal 
curl -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN" \
  "https://vibecode.bitrix24.com/v1/workday/schedule?id=1"

JavaScript — personal key

javascript 
const res = await fetch(
  'https://vibecode.bitrix24.com/v1/workday/schedule?id=1',
  { headers: { 'X-Api-Key': 'YOUR_API_KEY' } },
)
const { data } = await res.json()
if (Array.isArray(data) && data.length === 0) {
  console.log('Schedule not found')
} else {
  console.log('Schedule:', data.name)
  console.log('Type:', data.scheduleType)
}

JavaScript — OAuth application

javascript 
const res = await fetch(
  'https://vibecode.bitrix24.com/v1/workday/schedule?id=1',
  {
    headers: {
      'X-Api-Key': 'YOUR_APP_KEY',
      'Authorization': 'Bearer USER_SESSION_TOKEN',
    },
  },
)
const { data } = await res.json()

Response fields

When the schedule is found, data is an object with schedule details. When a schedule with the given id is absent, data is an empty array.

Field Type Description
success boolean true on a successful response
data object | array The schedule object or an empty array [] for a nonexistent identifier
data.id number Schedule identifier
data.name string Schedule name
data.scheduleType string Schedule type: FIXED (fixed), SHIFT (shift), FLEXTIME (flexible)
data.reportPeriod string Reporting period: MONTH, WEEK, TWO_WEEKS, QUARTER
data.reportPeriodOptions object Additional report period settings (for example, startWeekDay). Returned for all reportPeriod values
data.calendarId number Identifier of the calendar associated with the schedule
data.allowedDevices object Allowed tracking devices (browser, mobile). Each field is a boolean
data.deleted string "0" — the schedule is active; "1" — the schedule is deleted
data.isForAllUsers boolean true — the schedule applies to all employees
data.worktimeRestrictions array Array of work time restriction rules. An empty array — no restrictions
data.controlledActions number Number of controlled actions for the schedule
data.updatedBy number Identifier of the user who last updated the schedule. 0 — there were no updates
data.deletedBy number Identifier of the user who deleted the schedule. 0 — the schedule is not deleted
data.deletedAt string Deletion date and time. Empty string — the schedule is not deleted
data.createdBy number Identifier of the user who created the schedule. 0 — system creation
data.createdAt string Creation date and time (ISO 8601)
data.shifts array Array of shift objects for the schedule
data.shifts[].id number Shift identifier
data.shifts[].name string Shift name
data.shifts[].breakDuration number Break duration in seconds (3600 = 1 hour)
data.shifts[].workTimeStart number Shift start time in seconds from the start of the day (32400 = 09:00)
data.shifts[].workTimeEnd number Shift end time in seconds from the start of the day (64800 = 18:00)
data.shifts[].workDays string Days of the week as digits 1–7, where 1 = Monday, 7 = Sunday. "12345" — weekdays
data.shifts[].scheduleId number Identifier of the schedule the shift is bound to
data.shifts[].deleted boolean Deleted shift flag (boolean, unlike the string-typed data.deleted)
data.calendar object Details of the schedule's calendar
data.calendar.id number Calendar identifier
data.calendar.name string Calendar name
data.calendar.parentCalendarId number Parent calendar identifier
data.calendar.systemCode string Calendar system code
data.calendar.exclusions array List of calendar exclusions
data.scheduleViolationRules object Schedule violation rules. Fields with the value -1 mean "parameter not set"

Response example

A schedule with the given identifier is found (type FIXED, shift 09:00–18:00 Mon–Fri):

JSON 
{
  "success": true,
  "data": {
    "id": 9,
    "name": "Fixed schedule",
    "scheduleType": "FIXED",
    "reportPeriod": "MONTH",
    "reportPeriodOptions": { "startWeekDay": 0 },
    "calendarId": 37,
    "allowedDevices": { "browser": true, "mobile": true },
    "deleted": "0",
    "isForAllUsers": true,
    "worktimeRestrictions": [],
    "controlledActions": 3,
    "updatedBy": 0,
    "deletedBy": 0,
    "deletedAt": "",
    "createdBy": 1,
    "createdAt": "2026-05-05T11:50:40+00:00",
    "shifts": [
      {
        "id": 7,
        "name": "",
        "breakDuration": 3600,
        "workTimeStart": 32400,
        "workTimeEnd": 64800,
        "workDays": "12345",
        "scheduleId": 9,
        "deleted": false
      }
    ],
    "calendar": {
      "id": 37,
      "name": "",
      "parentCalendarId": 1,
      "systemCode": "",
      "exclusions": []
    },
    "scheduleViolationRules": {
      "id": 11,
      "scheduleId": 9,
      "entityCode": "UA",
      "maxExactStart": -1,
      "minExactEnd": -1,
      "maxOffsetStart": -1,
      "minOffsetEnd": -1,
      "relativeStartFrom": -1,
      "relativeStartTo": -1,
      "relativeEndFrom": -1,
      "relativeEndTo": -1,
      "minDayDuration": -1,
      "maxAllowedToEditWorkTime": -1,
      "maxWorkTimeLackForPeriod": -1,
      "periodTimeLackAgentId": 0,
      "maxShiftStartDelay": -1,
      "missedShiftStart": 0,
      "usersToNotify": {
        "fixedStartEnd": [],
        "fixedPerRecord": [],
        "fixedEditWorktime": [],
        "fixedPeriodic": [],
        "shiftDelay": [],
        "shiftMissedStart": []
      }
    }
  }
}

A schedule with the given identifier is not found:

JSON 
{
  "success": true,
  "data": []
}

Error response example

422 — the id parameter was not passed:

JSON 
{
  "success": false,
  "error": {
    "code": "BITRIX_ERROR",
    "message": "Could not find value for parameter {id}"
  }
}

Errors

HTTP Code Description
400 INVALID_PARAMS Bitrix24 returned INVALID_PARAMS — a request field failed validation
401 MISSING_API_KEY The X-Api-Key header was not passed
401 INVALID_API_KEY Invalid API key
401 KEY_EXPIRED The API key has expired
401 TOKEN_MISSING The key has no OAuth tokens configured for the portal
402 ACCOUNT_FROZEN The portal balance is frozen
403 SCOPE_DENIED The key lacks the timeman scope
422 BITRIX_ERROR Bitrix24 rejected the request — text is in message (for example, id was not passed or the user has no permission to view the schedule)
429 RATE_LIMITED The request limit to Bitrix24 was exceeded
502 BITRIX_UNAVAILABLE The Bitrix24 portal is unavailable

The full list of common API errors — Errors.

Known specifics

  • The type of the deleted field differs at different response levels. At the schedule level data.deleted is a string ("0"/"1"), inside a shift data.shifts[].deleted is a boolean (true/false). When writing client code you cannot handle both fields the same way.

See also