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 no schedule has that identifier, the endpoint returns 404 ENTITY_NOT_FOUND.

Parameters

Parameter In Type Required Default Description
Parameterid Inquery Typenumber Requiredyes Default— DescriptionSchedule identifier. Schedules and their identifiers are 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 body = await res.json()
if (!res.ok) {
  if (res.status === 404 && body.error?.code === 'ENTITY_NOT_FOUND') {
    console.log('Schedule not found')
  } else {
    throw new Error(body.error?.message ?? 'Could not get the schedule')
  }
} else {
  console.log('Schedule:', body.data.name)
  console.log('Type:', body.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

For a 200 response, data is an object with schedule details. If the schedule does not exist, the endpoint returns a 404 error without data.

Field Type Description
Fieldsuccess Typeboolean Descriptiontrue on a successful response
Fielddata Typeobject DescriptionThe schedule object
Fielddata.id Typenumber DescriptionSchedule identifier
Fielddata.name Typestring DescriptionSchedule name
Fielddata.scheduleType Typestring DescriptionSchedule type: FIXED (fixed), SHIFT (shift), FLEXTIME (flexible)
Fielddata.reportPeriod Typestring DescriptionReporting period: MONTH, WEEK, TWO_WEEKS, QUARTER
Fielddata.reportPeriodOptions Typeobject DescriptionAdditional report period settings (for example, startWeekDay). Returned for all reportPeriod values
Fielddata.calendarId Typenumber DescriptionIdentifier of the calendar associated with the schedule
Fielddata.allowedDevices Typeobject DescriptionAllowed tracking devices (browser, mobile). Each field is a boolean
Fielddata.deleted Typestring Description"0" — the schedule is active; "1" — the schedule is deleted
Fielddata.isForAllUsers Typeboolean Descriptiontrue — the schedule applies to all employees
Fielddata.worktimeRestrictions Typearray DescriptionArray of work time restriction rules. An empty array — no restrictions
Fielddata.controlledActions Typenumber DescriptionNumber of controlled actions for the schedule
Fielddata.updatedBy Typenumber DescriptionIdentifier of the user who last updated the schedule. 0 — the schedule has never been updated
Fielddata.deletedBy Typenumber DescriptionIdentifier of the user who deleted the schedule. 0 — the schedule is not deleted
Fielddata.deletedAt Typestring DescriptionDeletion date and time. An empty string — the schedule is not deleted
Fielddata.createdBy Typenumber DescriptionIdentifier of the user who created the schedule. 0 — created by the system
Fielddata.createdAt Typestring DescriptionCreation date and time (ISO 8601)
Fielddata.shifts Typearray DescriptionArray of shift objects for the schedule
Fielddata.shifts[].id Typenumber DescriptionShift identifier
Fielddata.shifts[].name Typestring DescriptionShift name
Fielddata.shifts[].breakDuration Typenumber DescriptionBreak duration in seconds (3600 = 1 hour)
Fielddata.shifts[].workTimeStart Typenumber DescriptionShift start time in seconds from the start of the day (32400 = 09:00)
Fielddata.shifts[].workTimeEnd Typenumber DescriptionShift end time in seconds from the start of the day (64800 = 18:00)
Fielddata.shifts[].workDays Typestring DescriptionDays of the week as digits 1–7, where 1 = Monday, 7 = Sunday. "12345" — weekdays
Fielddata.shifts[].scheduleId Typenumber DescriptionIdentifier of the schedule the shift is bound to
Fielddata.shifts[].deleted Typeboolean DescriptionDeleted shift flag (boolean, unlike the string-typed data.deleted)
Fielddata.calendar Typeobject DescriptionDetails of the schedule's calendar
Fielddata.calendar.id Typenumber DescriptionCalendar identifier
Fielddata.calendar.name Typestring DescriptionCalendar name
Fielddata.calendar.parentCalendarId Typenumber DescriptionParent calendar identifier
Fielddata.calendar.systemCode Typestring DescriptionCalendar system code
Fielddata.calendar.exclusions Typearray DescriptionList of calendar exclusions
Fielddata.scheduleViolationRules Typeobject DescriptionSchedule violation rules. Fields with the value -1 mean "parameter not set"

Response example

The schedule with the given identifier exists (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": []
      }
    }
  }
}

Error response example

400 — the id parameter was not passed:

JSON 
{
  "success": false,
  "error": {
    "code": "MISSING_REQUIRED_PARAMS",
    "message": "id is required — the schedule id, not a user id. Bitrix24 refuses this method without it."
  }
}

Errors

HTTP Code Description
HTTP400 CodeMISSING_REQUIRED_PARAMS DescriptionThe required schedule id was not passed
HTTP400 CodeINVALID_PARAMS DescriptionBitrix24 returned INVALID_PARAMS — a request field failed validation
HTTP401 CodeMISSING_API_KEY DescriptionThe X-Api-Key header was not passed
HTTP401 CodeINVALID_API_KEY DescriptionThe key is not recognized — no such key exists on the platform
HTTP401 CodeKEY_EXPIRED DescriptionThe API key has expired
HTTP401 CodeTOKEN_MISSING DescriptionThe key has no OAuth tokens configured for the portal
HTTP402 CodeACCOUNT_FROZEN DescriptionThe portal balance is frozen
HTTP403 CodeSCOPE_DENIED DescriptionThe key lacks the timeman scope
HTTP404 CodeENTITY_NOT_FOUND DescriptionNo schedule has the given id, or it was deleted
HTTP409 CodeTIMEMAN_MODULE_NOT_ENABLED DescriptionTime Management is not available on this portal: the module is not installed (not included in the plan), or the tool is switched off in portal settings. Ask a portal administrator to enable it — until then every timeman.* method answers the same way
HTTP422 CodeBITRIX_ERROR DescriptionBitrix24 rejected the request — the text is in message (for example, the user has no permission to view the schedule)
HTTP429 CodeRATE_LIMITED DescriptionThe rate limit for requests to Bitrix24 was exceeded
HTTP502 CodeBITRIX_UNAVAILABLE DescriptionThe 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). Do not handle the two fields the same way in client code.

See also