## 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 |
|----------|---|-----|:-----:|-----------|---------|
| `id` | query | number | yes | — | Schedule identifier. Schedules and their identifiers are configured in the work time tracking section of your Bitrix24 account |

## Examples

### curl — personal key

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

### curl — OAuth application

```bash
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 |
|------|-----|---------|
| `success` | boolean | `true` on a successful response |
| `data` | object | The schedule object |
| `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` — the schedule has never been updated |
| `data.deletedBy` | number | Identifier of the user who deleted the schedule. `0` — the schedule is not deleted |
| `data.deletedAt` | string | Deletion date and time. An empty string — the schedule is not deleted |
| `data.createdBy` | number | Identifier of the user who created the schedule. `0` — created by the system |
| `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

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 |
|------|-----|---------|
| 400 | `MISSING_REQUIRED_PARAMS` | The required schedule `id` was not passed |
| 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` | The key is not recognized — no such key exists on the platform |
| 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 |
| 404 | `ENTITY_NOT_FOUND` | No schedule has the given `id`, or it was deleted |
| 409 | `TIMEMAN_MODULE_NOT_ENABLED` | Time 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 |
| 422 | `BITRIX_ERROR` | Bitrix24 rejected the request — the text is in `message` (for example, the user has no permission to view the schedule) |
| 429 | `RATE_LIMITED` | The rate limit for requests to Bitrix24 was exceeded |
| 502 | `BITRIX_UNAVAILABLE` | The Bitrix24 portal is unavailable |

The full list of common API errors — [Errors](/docs/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

- [Tracking settings](/docs/workday/settings)
- [Current status](/docs/workday/status)
- [Workday history](/docs/workday/records)
- [Workday](/docs/workday)