Calendar settings

GET /v1/calendar/settings

Returns the calendar settings of the Bitrix24 account: the start and end of the work day, weekly days off, holidays, working weekend days, and the first day of the week. These are the same values the Bitrix24 interface uses to mark non-working days.

Parameters

No parameters.

Examples

curl — personal key

curl -H "X-Api-Key: YOUR_API_KEY" \
  https://vibecode.bitrix24.com/v1/calendar/settings

curl — OAuth application

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

JavaScript — personal key

const res = await fetch('https://vibecode.bitrix24.com/v1/calendar/settings', {
  headers: { 'X-Api-Key': 'YOUR_API_KEY' },
})
const { data, meta } = await res.json()

if (meta?.warnings?.some((w) => w.code === 'calendar_settings_partial')) {
  throw new Error('The key owner is not an employee of this account — the settings cannot be read')
}

const weekends = data.weekHolidays
const holidays = data.yearHolidays ? data.yearHolidays.split(',') : []
console.log('Work day:', data.workTimeStart, '—', data.workTimeEnd)
console.log('Weekly days off:', weekends.join(', '))
console.log('Holidays in the list:', holidays.length)

JavaScript — OAuth application

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

Response fields

Beyond the fields listed above, the response carries section addresses for non-standard calendar types — one field per type, named like path_to_type_location. Such field names arrive exactly as Bitrix24 returns them, so the response field set is not fixed.

Response example

{
  "success": true,
  "data": {
    "workTimeStart": "10",
    "workTimeEnd": "22",
    "yearHolidays": "",
    "yearWorkdays": "",
    "weekHolidays": ["SA", "SU"],
    "weekStart": "MO",
    "userNameTemplate": "#NAME# #LAST_NAME#",
    "syncByPush": "",
    "userShowLogin": "1",
    "pathToUser": "/company/personal/user/#user_id#/",
    "pathToUserCalendar": "/company/personal/user/#user_id#/calendar/",
    "pathToGroup": "/workgroups/group/#group_id#/",
    "pathToGroupCalendar": "/workgroups/group/#group_id#/calendar/",
    "pathToVr": "",
    "pathToRm": "",
    "rmIblockType": "",
    "rmIblockId": "",
    "depManagerSub": "1",
    "deniedSuperposeTypes": [],
    "pathesForSites": "",
    "pathes": [],
    "forumId": "1",
    "rmForSites": "1",
    "path_to_type_company_calendar": "/calendar/",
    "path_to_type_events": "",
    "path_to_type_location": "",
    "path_to_type_resource": ""
  }
}

Error response example

403 — the key has no calendar scope:

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

Errors

The full list of common API errors — Errors.

Known specifics

• A reduced response for a key owned by an external user. When the key owner is not an employee of the Bitrix24 account, Bitrix24 returns two fields — workTimeStart and workTimeEnd — carrying the default values 9 and 19 instead of the account settings. Such a response cannot be told apart from a configured account by its values alone, so the response carries meta.warnings with the code calendar_settings_partial. Check that field before you use the work day bounds. To read the full set of settings, use a key that belongs to an employee of the Bitrix24 account.

• Values arrive as strings, and an unset field arrives as an empty string. An option that is on arrives as "1", and an option that is off arrives as an empty string. The endpoint never returns Y or N, so comparing against N gives a wrong result on every configured account. Test the value for truthiness instead of comparing it with a specific string. An option that was never saved for the account arrives as a boolean rather than a string, so the handler must accept both forms.

• An empty holiday list does not mean there are no holidays. An empty string means the list is not filled in for the account, not that the year has no holidays.

• A non-empty list does not mean an administrator filled it in. The yearHolidays and yearWorkdays fields have three states, not two: an administrator filled the list in; the list is empty; or the administrator never opened the settings and a localised default set arrived. The third state is indistinguishable from the first by the response alone. The default set is chosen by account language rather than by country, and for some languages it matches the Russian one — an account in another country using a language from that group returns Russian holidays. Do not mark up a calendar from it as if it were confirmed data.

• A day arrives both with and without a leading zero. The same holiday reads as 1.01 or 01.01 depending on the account language. Comparing against one form only fails silently: there is no error, the day simply comes out as a working one. Normalise both the list entries and the lookup key to a single form.

• A limit of 120 requests per minute per Bitrix24 account. A limit of this endpoint alone, on top of the shared request limit to Bitrix24. It exists because reading the settings can make Bitrix24 write a service option of the account, so frequent polling costs more than an ordinary read. The settings change rarely — cache the response on your side instead of polling.

• The settings belong to the whole Bitrix24 account. The response does not depend on whose calendar is read and carries no personal preferences of an employee.

• Hours are given in the time zone of the Bitrix24 account. workTimeStart and workTimeEnd are hours rather than full timestamps, so comparing them with an event timestamp requires converting to the time zone of the account.

See also

• Endpoints
• Calendar
• Calendar events
• Calendar sections