## Event fields

`GET /v1/calendar-events/fields`

Returns the event field schema: type, readonly flag, available batch operations.

## Examples

### curl — personal key

```bash
curl "https://vibecode.bitrix24.com/v1/calendar-events/fields" \
  -H "X-Api-Key: YOUR_API_KEY"
```

### curl — OAuth application

```bash
curl "https://vibecode.bitrix24.com/v1/calendar-events/fields" \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN"
```

### JavaScript — personal key

```javascript
const res = await fetch('https://vibecode.bitrix24.com/v1/calendar-events/fields', {
  headers: {
    'X-Api-Key': 'YOUR_API_KEY',
  },
})

const { success, data } = await res.json()
console.log('Fields:', Object.keys(data.fields).length)
```

### JavaScript — OAuth application

```javascript
const res = await fetch('https://vibecode.bitrix24.com/v1/calendar-events/fields', {
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
  },
})

const { success, data } = await res.json()
```

## Response fields

The `label` and `description` field captions are returned in English. Request headers do not switch the language.

| Field | Type | Description |
|------|-----|---------|
| `success` | boolean | Always `true` on success |
| `data.fields` | object | The event field schema: field name → `type`, `readonly`, `label`, `description`. Every field of the map is listed in the table below |
| `data.relations` | object | Event links to employees: `owner`, `host`, and `attendee`, all three pointing to users. `owner` and `host` carry `includable: true` |
| `data.batch` | array | Event operations available in [`POST /v1/batch`](/docs/batch): `create`, `update`, `delete` |
| `data.include` | array | The names the `include` parameter accepts in [List events](./list.md) and [Get an event](./get.md): `owner`, `host`, `attendee` |

### Fields of the `data.fields` map

| Field | Type | RO | Description |
|------|-----|:--:|---------|
| `id` | number | yes | Event ID |
| `parentId` | number | yes | Parent event ID (for recurring events, matches the `id` of the source event) |
| `active` | boolean | yes | Whether the event is active. Returned in the `GET /v1/calendar-events` list, absent from the `GET /v1/calendar-events/:id` response |
| `deleted` | boolean | yes | Deletion flag |
| `name` | string | | Name |
| `description` | string | | Description |
| `type` | string | | Calendar type: `user`, `group`, `company_calendar` |
| `ownerId` | number | | Calendar owner ID. Employee lookup: `GET /v1/users` |
| `from` | datetime | | Start (ISO 8601) |
| `to` | datetime | | End (ISO 8601) |
| `skipTime` | boolean | | All-day event. When `true`, the event covers the calendar days from `from` through `to`, inclusive |
| `durationSeconds` | number | yes | Event duration in seconds |
| `importance` | string | | Importance: `high`, `normal`, `low` |
| `accessibility` | string | | Busy status: `busy`, `quest`, `free`, `absent` |
| `location` | string | | Event location |
| `color` | string | | Event color (HEX) |
| `textColor` | string | | Event text color (HEX). Returned in the `GET /v1/calendar-events` list, absent from the `GET /v1/calendar-events/:id` response |
| `sectionId` | number | | Calendar section ID |
| `isPrivate` | boolean | | Private event |
| `isMeeting` | boolean | | Meeting event with invitations. On `POST` and `PATCH`, pass it as `true` together with `attendees`; otherwise, the attendees are not stored |
| `attendees` | number[] | | Array of employee IDs to invite. List: `GET /v1/users`. Stored only together with `isMeeting: true` in the same request; without the flag it is silently ignored. Whether the IDs exist is not checked: any number becomes an attendee `U<id>`. CRM elements are linked with the `crmFields` field. **Write-only** — this field is not returned in event responses; attendees are available in `attendeeList`, `attendeesCodes` |
| `attendeesCodes` | string[] | yes | Internal Bitrix24 attendee codes (format `U<id>`) |
| `attendeeList` | array | yes | Extended attendee list: `{ id, entryId, status }`, where `status` is `Y` (accepted), `H` (host), `Q` (tentative), `N` (declined) |
| `remind` | array | | Reminder settings |
| `rrule` | object | | Recurrence schedule of a recurring event: frequency (`FREQ`), interval (`INTERVAL`), days of the week (`BYDAY`), series boundary (`UNTIL` or `COUNT`). On read, `BYDAY` comes back as a dictionary object such as `{"MO":"MO"}`, and `UNTIL` is a date string in the Bitrix24 account's regional format that Bitrix24 fills in even when `COUNT` is set |
| `crmFields` | string[] | | CRM elements the event is linked to: `D_<id>` deal, `C_<id>` contact, `L_<id>` lead, `CO_<id>` company. Element lists: `GET /v1/deals`, `GET /v1/contacts`, `GET /v1/leads`, `GET /v1/companies`. An event with no links returns `[]`. Clearing every link with an empty array works on `POST` and `PATCH`; in a batch request an empty array is refused: `POST /v1/batch` — `INVALID_PARAMS` in `data.errors` under the call's `id`, `POST /v1/calendar-events/batch` — `400 BATCH_ITEM_VALIDATION` for the whole batch (the name `INVALID_PARAMS` and the item index arrive inside `message`) |
| `createdBy` | number | yes | Event creator ID. Lookup: `GET /v1/users` |
| `dateCreate` | string | yes | Creation date. A Bitrix24-formatted string that depends on the account's regional settings (for example `08.06.2026 17:29:51` or `06/08/2026 05:29:51 pm`). This is not ISO 8601 — do not parse it with a fixed parser |
| `updatedAt` | string | yes | Last modification date. A string in the same regional format as `dateCreate`. This is not ISO 8601 |
| `meetingStatus` | string | yes | Participation status of the calendar owner: `Y` (accepted), `H` (host), `Q` (tentative), `N` (declined) |
| `meetingHost` | number | yes | Meeting organizer ID. Lookup: `GET /v1/users`. For an event in a group calendar that is not a meeting — `type: group` and `isMeeting: false` — the field holds the ID of the workgroup that owns the calendar, not an employee ID. The creator of such an event is in `createdBy` |
| `eventType` | string | yes | Technical event type (for system events) |
| `syncStatus` | string | yes | Synchronization status with external calendars |
| `recurrenceId` | number | yes | Recurring event series ID |
| `collabId` | number | yes | Collaboration ID (when external users participate) |
| `occurrenceIndex` | number | yes | Zero-based index of the occurrence within an expanded recurring series. The rows of a series share one `id` — the `id` + `occurrenceIndex` pair uniquely identifies a row in the set |
| `version` | number | yes | Monotonic change counter of the event — increases on every modification and does not depend on regional settings. Compare `id` + `version` pairs to find updated events without parsing dates |

Unset scalar fields are returned as `null`, empty arrays as `[]`. In a minimal event, for example, `eventType`, `description`, `location`, `color`, `textColor`, `rrule`, `recurrenceId`, `syncStatus`, `collabId` come back as `null`, while `remind` comes back as an empty array `[]`.

**The fields `dateFrom` / `dateTo` do not exist** — the event start and end live in `from` / `to`. The original Bitrix24 names `DATE_FROM` / `DATE_TO` are accepted in `select` as aliases and map to the canonical `from` / `to`. An unknown name in `select` on this entity returns `400 UNKNOWN_SELECT_FIELD` with the list of accepted names.

## Response example

```json
{
  "success": true,
  "data": {
    "fields": {
      "id": { "type": "number", "readonly": true, "label": "Event ID", "description": "Unique identifier of the calendar event." },
      "name": { "type": "string", "readonly": false, "label": "Name", "description": "Name of the calendar event." },
      "type": { "type": "string", "readonly": false, "label": "Calendar type", "description": "Type of the event's calendar: personal, group, or company-wide calendar." },
      "ownerId": { "type": "number", "readonly": false, "label": "Calendar owner ID", "description": "Identifier of the calendar owner — an employee or a workgroup." },
      "from": { "type": "datetime", "readonly": false, "label": "Event start", "description": "Start date and time of the event in ISO 8601 format with timezone offset." },
      "to": { "type": "datetime", "readonly": false, "label": "Event end", "description": "End date and time of the event in ISO 8601 format with timezone offset." },
      "skipTime": { "type": "boolean", "readonly": false, "label": "All-day event", "description": "Indicates that the event lasts the whole day without a specific time." },
      "durationSeconds": { "type": "number", "readonly": true, "label": "Duration in seconds", "description": "Duration of the event in seconds." },
      "importance": { "type": "string", "readonly": false, "label": "Importance", "description": "Importance level of the event: high, normal, or low." },
      "accessibility": { "type": "string", "readonly": false, "label": "Busy status", "description": "Owner's busy status during the event: busy, tentative, free, or absent." },
      "sectionId": { "type": "number", "readonly": false, "label": "Calendar section ID", "description": "Identifier of the calendar section the event is recorded in." },
      "attendees": { "type": "array", "readonly": false, "label": "Invited attendees", "description": "Array of employee IDs invited to the event — write-only field; attendees are returned in the response via attendeeList and attendeesCodes." },
      "rrule": { "type": "object", "readonly": false, "label": "Recurrence rule", "description": "Recurrence schedule of a recurring event: frequency, interval, days of week, and series end condition." },
      "crmFields": { "type": "array", "readonly": false, "label": "CRM elements", "description": "CRM elements the event is linked to — an array of typed references: `D_<id>` deal, `C_<id>` contact, `L_<id>` lead, `CO_<id>` company. The value must be an array on create and update. An empty array clears every link, and omitting the field keeps the stored links; clearing works on POST and PATCH only — in a batch request an empty array is refused: `POST /v1/batch` answers `INVALID_PARAMS` in `data.errors` under this call's `id`, `POST /v1/calendar-events/batch` answers `400 BATCH_ITEM_VALIDATION` for the whole batch (the name `INVALID_PARAMS` and the item index arrive inside `message`). An event with no links reads back as `[]`. An unknown prefix, or a reference to a record that does not exist, is rejected." },
      "dateCreate": { "type": "string", "readonly": true, "label": "Creation date", "description": "Date and time the event was created, in a string format that depends on the portal's regional settings." },
      "updatedAt": { "type": "string", "readonly": true, "label": "Modification date", "description": "Date and time the event was last modified, in a string format that depends on the portal's regional settings." },
      "occurrenceIndex": { "type": "number", "readonly": true, "label": "Occurrence index", "description": "Zero-based index of this occurrence within an expanded recurring series. Recurring events are returned as one row per occurrence sharing the same id — the pair (id, occurrenceIndex) uniquely identifies a row." },
      "version": { "type": "number", "readonly": true, "label": "Change version", "description": "Monotonic change counter maintained by Bitrix24 — increases on every modification. Locale-independent change marker: diff (id, version) pairs to detect updated events without parsing dates." }
    },
    "relations": {
      "owner": { "type": "one", "entity": "users", "includable": true },
      "host": { "type": "one", "entity": "users", "includable": true },
      "attendee": { "type": "many", "entity": "users", "operations": [] }
    },
    "batch": ["create", "update", "delete"],
    "include": ["owner", "host", "attendee"]
  }
}
```

## Error response example

403 — no scope:

```json
{
  "success": false,
  "error": {
    "code": "SCOPE_DENIED",
    "message": "This endpoint requires 'calendar' scope"
  }
}
```

## Errors

| HTTP | Code | Description |
|------|-----|---------|
| 403 | `SCOPE_DENIED` | The API key does not have the `calendar` scope |
| 401 | `TOKEN_MISSING` | The API key has no configured tokens |
| 429 | `RATE_LIMITED` | Rate limit exceeded: 300 requests per minute per portal. All API keys of the portal share one limit. The current limit is returned in the `x-ratelimit-limit` header. Retry after the delay in the `Retry-After` header |

For the full list of common API errors, see [Errors](/docs/errors).

## See also

- [Create event](./create.md)
- [Update event](./update.md)
- [List events](./list.md)