## 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

```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 { 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](/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`). When writing client code you cannot handle both fields the same way.

## See also

- [Tracking settings](/docs/workday/settings) — `GET /v1/workday/settings`.
- [Current status](/docs/workday/status) — `GET /v1/workday/status`.
- [Workday](/docs/workday) — section overview.