لوكلاء AI: ملف markdown لهذه الصفحة — /docs-content-en/entities/calendar-events.md فهرس التوثيق — /llms.txt

مقالات التوثيق متاحة حاليًا باللغة الإنجليزية فقط.

Calendar events

Manage events in Bitrix24 calendars: personal, group, and company. You can create, retrieve, update, and delete events, and retrieve the field schema.

Bitrix24 API: calendar.event.* Scope: calendar

Create event

POST /v1/calendar-events

Creates a new event in the specified calendar.

Request fields (body)

Field Type Required Description
Fieldtype Typestring Requiredyes DescriptionCalendar type: user, group, company_calendar
FieldownerId Typenumber Requiredyes DescriptionCalendar owner ID: employee (GET /v1/users) or workgroup
Fieldname Typestring Requiredyes DescriptionEvent title
Fieldfrom Typedatetime Requiredyes DescriptionEvent start in ISO 8601. Accepts a string with an explicit offset (2026-06-10T10:00:00+00:00), in UTC (2026-06-10T07:00:00Z), or without a zone (2026-06-10T10:00:00)
Fieldto Typedatetime Requiredyes DescriptionEvent end in ISO 8601. Accepts a string with an explicit offset (2026-06-10T11:00:00+00:00), in UTC (2026-06-10T08:00:00Z), or without a zone (2026-06-10T11:00:00)
FieldtimezoneFrom Typestring Requiredno DescriptionEvent start timezone (IANA name: UTC, Asia/Almaty). Without it, the timezone of the employee who owns the API key is used
FieldtimezoneTo Typestring Requiredno DescriptionEvent end timezone (IANA name)
Fielddescription Typestring Requiredno DescriptionDescription
FieldsectionId Typenumber Requiredno DescriptionCalendar section ID. If the field is not passed, a new section is created on every call. To have events written to a single section, pass the sectionId of an existing section. The ID of an existing section is returned by GET /v1/calendar-events in the sectionId field of any previously created event
FieldskipTime Typeboolean Requiredno DescriptionAll-day event. When true, the time in from/to is ignored and the duration is fixed at 24 hours
Fieldimportance Typestring Requiredno Descriptionhigh, normal, low
Fieldaccessibility Typestring Requiredno DescriptionAvailability: busy, quest (tentative), free, absent
Fieldlocation Typestring Requiredno DescriptionVenue
Fieldcolor Typestring Requiredno DescriptionEvent color (HEX, #RRGGBB)
Fieldattendees Typenumber[] Requiredno DescriptionArray of invited employee IDs. List: GET /v1/users. Stored only if the same request passes isMeeting: true. Without the flag the array is ignored with no error and no warning. IDs are not checked for existence: any number becomes an attendee U<id>, and a string such as C_<id> produces the code U0 in attendeesCodes. CRM elements are linked with the crmFields field. Write-only — in the response, attendees are returned in the attendeeList and attendeesCodes fields. See Event fields
Fieldremind Typearray Requiredno DescriptionReminder settings. Each item: {type: 'min' | 'hour' | 'day', count: <number>}
Fieldrrule Typeobject Requiredno DescriptionRecurrence schedule of a recurring event. For the field structure and an example, see the Recurring event section below
FieldisPrivate Typeboolean Requiredno DescriptionPrivate event — details are hidden from other users
FieldisMeeting Typeboolean Requiredno DescriptionMeeting event with invitations. Pass true for the attendees array to be stored
FieldcrmFields Typestring[] Requiredno DescriptionCRM elements to link the event 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. The value must be an array. An unknown prefix, or a reference to a record that does not exist, is rejected

Full field list: GET /v1/calendar-events/fields.

Examples

curl — personal key

Terminal 
curl -X POST "https://vibecode.bitrix24.com/v1/calendar-events" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "user",
    "ownerId": 1,
    "name": "Team call",
    "from": "2026-06-10T10:00:00",
    "to": "2026-06-10T11:00:00",
    "timezoneFrom": "UTC",
    "timezoneTo": "UTC",
    "description": "Weekly sync",
    "accessibility": "busy",
    "sectionId": 3
  }'

curl — OAuth application

Terminal 
curl -X POST "https://vibecode.bitrix24.com/v1/calendar-events" \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "user",
    "ownerId": 1,
    "name": "Team call",
    "from": "2026-06-10T10:00:00",
    "to": "2026-06-10T11:00:00",
    "timezoneFrom": "UTC",
    "timezoneTo": "UTC",
    "description": "Weekly sync",
    "accessibility": "busy",
    "sectionId": 3
  }'

JavaScript — personal key

javascript 
const res = await fetch('https://vibecode.bitrix24.com/v1/calendar-events', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    type: 'user',
    ownerId: 1,
    name: 'Team call',
    from: '2026-06-10T10:00:00',
    to: '2026-06-10T11:00:00',
    timezoneFrom: 'UTC',
    timezoneTo: 'UTC',
    description: 'Weekly sync',
    accessibility: 'busy',
    sectionId: 3,
  }),
})

const { success, data } = await res.json()
console.log('Event ID:', data.id)

JavaScript — OAuth application

javascript 
const res = await fetch('https://vibecode.bitrix24.com/v1/calendar-events', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    type: 'user',
    ownerId: 1,
    name: 'Team call',
    from: '2026-06-10T10:00:00',
    to: '2026-06-10T11:00:00',
    timezoneFrom: 'UTC',
    timezoneTo: 'UTC',
    description: 'Weekly sync',
    accessibility: 'busy',
    sectionId: 3,
  }),
})

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

Recurring event

To create a recurring event, pass the rrule field as an object. Request:

Terminal 
curl -X POST "https://vibecode.bitrix24.com/v1/calendar-events" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "user",
    "ownerId": 1,
    "name": "Team call",
    "from": "2026-07-13T10:00:00",
    "to": "2026-07-13T11:00:00",
    "timezoneFrom": "UTC",
    "timezoneTo": "UTC",
    "rrule": {
      "FREQ": "WEEKLY",
      "INTERVAL": 1,
      "BYDAY": ["MO", "WE"],
      "UNTIL": "2026-09-30"
    }
  }'

A single event with one id is created — the list (GET /v1/calendar-events) will return one item per occurrence in the series, all sharing a common parentId. Deleting the event (DELETE /v1/calendar-events/:id) removes the entire series.

rrule fields:

Field Type Description
FieldFREQ Typestring DescriptionFrequency: DAILY, WEEKLY, MONTHLY, YEARLY
FieldINTERVAL Typenumber DescriptionInterval. 1 — every cycle, 2 — every other, and so on
FieldBYDAY Typestring[] DescriptionDays of the week for WEEKLY: SU, MO, TU, WE, TH, FR, SA
FieldUNTIL Typedate DescriptionSeries end date in YYYY-MM-DD format. Alternative — COUNT
FieldCOUNT Typenumber DescriptionNumber of repetitions. Alternative — UNTIL

Response fields

Field Type Description
Fieldsuccess Typeboolean DescriptionAlways true on success
Fielddata Typeobject DescriptionThe created event (all fields — see Event fields)

The URL of the event card in Bitrix24 depends on the calendar type:

type URL
typeuser URLhttps://<portal>.bitrix24.com/company/personal/user/<ownerId>/calendar/?EVENT_ID=<id>&EVENT_DATE=<dd.mm.yyyy>
typegroup URLhttps://<portal>.bitrix24.com/workgroups/group/<ownerId>/calendar/?EVENT_ID=<id>&EVENT_DATE=<dd.mm.yyyy>
typecompany_calendar URLhttps://<portal>.bitrix24.com/calendar/?EVENT_ID=<id>&EVENT_DATE=<dd.mm.yyyy>

<dd.mm.yyyy> — the event start date (the from field) in dot-separated "day.month.year" format. <portal> — your Bitrix24 portal domain. Access is limited by the employee's permissions in Bitrix24.

Response example

JSON 
{
  "success": true,
  "data": {
    "id": 7773,
    "parentId": 7773,
    "deleted": false,
    "type": "user",
    "ownerId": 1,
    "name": "Team call",
    "from": "2026-06-10T10:00:00+00:00",
    "to": "2026-06-10T11:00:00+00:00",
    "skipTime": false,
    "durationSeconds": 3600,
    "createdBy": 1,
    "dateCreate": "06/05/2026 09:12:00 am",
    "updatedAt": "06/05/2026 09:12:00 am",
    "description": "Weekly sync",
    "accessibility": "busy",
    "importance": "normal",
    "isMeeting": false,
    "meetingStatus": "H",
    "meetingHost": 1,
    "sectionId": 3,
    "attendeeList": [
      { "id": 1, "entryId": "7773", "status": "H" }
    ]
  }
}

Error response example

422 — a required field was not passed:

JSON 
{
  "success": false,
  "error": {
    "code": "BITRIX_ERROR",
    "message": "Required parameter \"name\" is not set for the \"calendar.event.add\" method"
  }
}

Errors

HTTP Code Description
HTTP422 CodeBITRIX_ERROR DescriptionA required field was not passed (type, ownerId, name, from, to)
HTTP400 CodeREADONLY_FIELD DescriptionA read-only field was passed in the request body (id, createdBy, dateCreate, updatedAt)
HTTP403 CodeSCOPE_DENIED DescriptionThe API key does not have the calendar scope
HTTP401 CodeTOKEN_MISSING DescriptionThe API key has no configured tokens

Full list of common API errors — Errors.

Known specifics

Section buildup when creating without sectionId. If the sectionId field is not passed, a new calendar section is created on every call. Over a series of calls without sectionId, empty sections accumulate in the employee's calendar and are visible in the Bitrix24 web interface. To have all events written to a single section, pass the sectionId of an existing section — its ID can be taken from the GET /v1/calendar-events response.

See also