Calendar: Imports

Base URL: $BUSINESS_API

Parse an ICS or CSV calendar into a preview

Logs

POST /calendar/imports

Parses an ICS or CSV calendar, sent inline in content or fetched from url (10 second timeout, 4 MB limit), and stores a preview that lists the days and rules it would add, change or remove, the conflicts with existing days, and the schedules the change may move. Nothing is written to the calendar unless auto_apply is true and the preview has no conflicts; otherwise apply it later with the apply endpoint. ICS input must use all-day events with optional yearly RRULEs; multi-day events, EXDATE and timed starts are rejected with 400. When source_id is given the source must exist and be enabled, and days or rules that the source previously supplied but no longer contains are reported as removals and conflicts. Requires automations:write.

Body application/json

formatstring · required

one of ics, csv

contentstring · optional
urlstring · optional
source_idstring · optional
auto_applyboolean · optional

Returns

201 Import preview with added, changed, removed, conflicts, affected schedules and explicit coverage limitations

Show attributes
idstring · optional
tenant_idstring · optional
source_idstring · optional
formatstring · optional

one of ics, csv

statusstring · optional

one of preview, applied, failed

itemsarray of CalendarImportItem · optional
Show child attributes
kindstring · optional
uidstring · optional
datestring (date) · optional
monthinteger · optional
dayinteger · optional
weekdayinteger · optional
positioninteger · optional
easter_kindstring · optional

one of western, orthodox

easter_offsetinteger · optional
observedstring · optional

one of none, next, previous, nearest

valid_fromstring (date) · optional
valid_tostring (date) · optional
name_ptstring · optional
name_enstring · optional
kind_of_daystring · optional

one of holiday, closure, working

area_idstring · optional
source_refstring · optional
addedarray of CalendarImportItem · optional
Show child attributes
kindstring · optional
uidstring · optional
datestring (date) · optional
monthinteger · optional
dayinteger · optional
weekdayinteger · optional
positioninteger · optional
easter_kindstring · optional

one of western, orthodox

easter_offsetinteger · optional
observedstring · optional

one of none, next, previous, nearest

valid_fromstring (date) · optional
valid_tostring (date) · optional
name_ptstring · optional
name_enstring · optional
kind_of_daystring · optional

one of holiday, closure, working

area_idstring · optional
source_refstring · optional
changedarray of CalendarImportItem · optional
Show child attributes
kindstring · optional
uidstring · optional
datestring (date) · optional
monthinteger · optional
dayinteger · optional
weekdayinteger · optional
positioninteger · optional
easter_kindstring · optional

one of western, orthodox

easter_offsetinteger · optional
observedstring · optional

one of none, next, previous, nearest

valid_fromstring (date) · optional
valid_tostring (date) · optional
name_ptstring · optional
name_enstring · optional
kind_of_daystring · optional

one of holiday, closure, working

area_idstring · optional
source_refstring · optional
removedarray of CalendarImportItem · optional
Show child attributes
kindstring · optional
uidstring · optional
datestring (date) · optional
monthinteger · optional
dayinteger · optional
weekdayinteger · optional
positioninteger · optional
easter_kindstring · optional

one of western, orthodox

easter_offsetinteger · optional
observedstring · optional

one of none, next, previous, nearest

valid_fromstring (date) · optional
valid_tostring (date) · optional
name_ptstring · optional
name_enstring · optional
kind_of_daystring · optional

one of holiday, closure, working

area_idstring · optional
source_refstring · optional
conflictsarray of object · optional
Show child attributes
datestring (date) · optional
existing_kindstring · optional

one of holiday, closure, working

incoming_kindstring · optional

one of holiday, closure, working

detailstring · optional
affectedarray of object · optional
Show child attributes
typestring · required
idstring · required
namestring · optional
fromstring (date-time) · optional
tostring (date-time) · optional
countinteger · required
affected_limitationsarray of string · optional

Consumer coverage gaps and date behaviors not recalculated by this preview.

confirmed_bystring · optional
outcomestring · optional
created_atstring (date-time) · optional
applied_atstring (date-time) · optional

Permissions automations:write · Roles: admin, finance, operations, owner

curl -X POST "$BUSINESS_API/calendar/imports" \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{
  "format": "ics",
  "content": "content",
  "url": "https://example.org/",
  "source_id": "sou_2fjWEpPCsLRCQBV64hz26xd8MF9",
  "auto_apply": true
}'
Response 201
{
  "id": "cal_26gTtQiVPucb3CyVJaoRD6UlbOQ",
  "tenant_id": "ten_2ugFXIC316WXzGu1HGal90AxTA6",
  "source_id": "sou_2fjWEpPCsLRCQBV64hz26xd8MF9",
  "format": "ics",
  "status": "preview",
  "items": [
    {
      "kind": "active",
      "uid": "uid",
      "date": "2026-11-19",
      "month": 1,
      "day": 1,
      "weekday": 1,
      "position": 1,
      "easter_kind": "western",
      "easter_offset": 1,
      "observed": "none",
      "valid_from": "2026-11-19",
      "valid_to": "2026-11-19",
      "name_pt": "name pt",
      "name_en": "name en",
      "kind_of_day": "holiday",
      "area_id": "are_2ZTQYjrK63ZImD3sMz1O2BhWeZV",
      "source_ref": "source ref"
    }
  ],
  "added": [
    {
      "kind": "active",
      "uid": "uid",
      "date": "2026-11-19",
      "month": 1,
      "day": 1,
      "weekday": 1,
      "position": 1,
      "easter_kind": "western",
      "easter_offset": 1,
      "observed": "none",
      "valid_from": "2026-11-19",
      "valid_to": "2026-11-19",
      "name_pt": "name pt",
      "name_en": "name en",
      "kind_of_day": "holiday",
      "area_id": "are_2ZTQYjrK63ZImD3sMz1O2BhWeZV",
      "source_ref": "source ref"
    }
  ],
  "changed": [
    {
      "kind": "active",
      "uid": "uid",
      "date": "2026-11-19",
      "month": 1,
      "day": 1,
      "weekday": 1,
      "position": 1,
      "easter_kind": "western",
      "easter_offset": 1,
      "observed": "none",
      "valid_from": "2026-11-19",
      "valid_to": "2026-11-19",
      "name_pt": "name pt",
      "name_en": "name en",
      "kind_of_day": "holiday",
      "area_id": "are_2ZTQYjrK63ZImD3sMz1O2BhWeZV",
      "source_ref": "source ref"
    }
  ],
  "removed": [
    {
      "kind": "active",
      "uid": "uid",
      "date": "2026-11-19",
      "month": 1,
      "day": 1,
      "weekday": 1,
      "position": 1,
      "easter_kind": "western",
      "easter_offset": 1,
      "observed": "none",
      "valid_from": "2026-11-19",
      "valid_to": "2026-11-19",
      "name_pt": "name pt",
      "name_en": "name en",
      "kind_of_day": "holiday",
      "area_id": "are_2ZTQYjrK63ZImD3sMz1O2BhWeZV",
      "source_ref": "source ref"
    }
  ],
  "conflicts": [
    {
      "date": "2026-11-19",
      "existing_kind": "holiday",
      "incoming_kind": "holiday",
      "detail": "detail"
    }
  ],
  "affected": [
    {
      "type": "active",
      "id": "cal_26gTtQiVPucb3CyVJaoRD6UlbOQ",
      "name": "Ana Matsinhe",
      "from": "2026-11-19T09:30:00Z",
      "to": "2026-11-19T09:30:00Z",
      "count": 1
    }
  ],
  "affected_limitations": [
    "affected limitation"
  ],
  "confirmed_by": "confirmed by",
  "outcome": "outcome",
  "created_at": "2026-11-19T09:30:00Z",
  "applied_at": "2026-11-19T09:30:00Z"
}

Read a calendar import preview or outcome

Logs

GET /calendar/imports/{id}

Returns a stored import with its status (preview, applied or failed), the parsed items, the added, changed and removed entries, conflicts, affected schedules and the known limits of that affected-schedule analysis. After an apply it also shows who confirmed it, when, and a short outcome. Requires automations:read.

Parameters

idstring · path · required

Id of the calendar import returned when it was created (prefix cim).

Returns

200 Import

Show attributes
idstring · optional
tenant_idstring · optional
source_idstring · optional
formatstring · optional

one of ics, csv

statusstring · optional

one of preview, applied, failed

itemsarray of CalendarImportItem · optional
Show child attributes
kindstring · optional
uidstring · optional
datestring (date) · optional
monthinteger · optional
dayinteger · optional
weekdayinteger · optional
positioninteger · optional
easter_kindstring · optional

one of western, orthodox

easter_offsetinteger · optional
observedstring · optional

one of none, next, previous, nearest

valid_fromstring (date) · optional
valid_tostring (date) · optional
name_ptstring · optional
name_enstring · optional
kind_of_daystring · optional

one of holiday, closure, working

area_idstring · optional
source_refstring · optional
addedarray of CalendarImportItem · optional
Show child attributes
kindstring · optional
uidstring · optional
datestring (date) · optional
monthinteger · optional
dayinteger · optional
weekdayinteger · optional
positioninteger · optional
easter_kindstring · optional

one of western, orthodox

easter_offsetinteger · optional
observedstring · optional

one of none, next, previous, nearest

valid_fromstring (date) · optional
valid_tostring (date) · optional
name_ptstring · optional
name_enstring · optional
kind_of_daystring · optional

one of holiday, closure, working

area_idstring · optional
source_refstring · optional
changedarray of CalendarImportItem · optional
Show child attributes
kindstring · optional
uidstring · optional
datestring (date) · optional
monthinteger · optional
dayinteger · optional
weekdayinteger · optional
positioninteger · optional
easter_kindstring · optional

one of western, orthodox

easter_offsetinteger · optional
observedstring · optional

one of none, next, previous, nearest

valid_fromstring (date) · optional
valid_tostring (date) · optional
name_ptstring · optional
name_enstring · optional
kind_of_daystring · optional

one of holiday, closure, working

area_idstring · optional
source_refstring · optional
removedarray of CalendarImportItem · optional
Show child attributes
kindstring · optional
uidstring · optional
datestring (date) · optional
monthinteger · optional
dayinteger · optional
weekdayinteger · optional
positioninteger · optional
easter_kindstring · optional

one of western, orthodox

easter_offsetinteger · optional
observedstring · optional

one of none, next, previous, nearest

valid_fromstring (date) · optional
valid_tostring (date) · optional
name_ptstring · optional
name_enstring · optional
kind_of_daystring · optional

one of holiday, closure, working

area_idstring · optional
source_refstring · optional
conflictsarray of object · optional
Show child attributes
datestring (date) · optional
existing_kindstring · optional

one of holiday, closure, working

incoming_kindstring · optional

one of holiday, closure, working

detailstring · optional
affectedarray of object · optional
Show child attributes
typestring · required
idstring · required
namestring · optional
fromstring (date-time) · optional
tostring (date-time) · optional
countinteger · required
affected_limitationsarray of string · optional

Consumer coverage gaps and date behaviors not recalculated by this preview.

confirmed_bystring · optional
outcomestring · optional
created_atstring (date-time) · optional
applied_atstring (date-time) · optional

Errors 404

Permissions automations:read · Roles: admin, analyst, customer_service, finance, operations, owner

curl -X GET "$BUSINESS_API/calendar/imports/{id}" \
  -H "Authorization: Bearer sk_test_..."
Response 200
{
  "id": "cal_26gTtQiVPucb3CyVJaoRD6UlbOQ",
  "tenant_id": "ten_2ugFXIC316WXzGu1HGal90AxTA6",
  "source_id": "sou_2fjWEpPCsLRCQBV64hz26xd8MF9",
  "format": "ics",
  "status": "preview",
  "items": [
    {
      "kind": "active",
      "uid": "uid",
      "date": "2026-11-19",
      "month": 1,
      "day": 1,
      "weekday": 1,
      "position": 1,
      "easter_kind": "western",
      "easter_offset": 1,
      "observed": "none",
      "valid_from": "2026-11-19",
      "valid_to": "2026-11-19",
      "name_pt": "name pt",
      "name_en": "name en",
      "kind_of_day": "holiday",
      "area_id": "are_2ZTQYjrK63ZImD3sMz1O2BhWeZV",
      "source_ref": "source ref"
    }
  ],
  "added": [
    {
      "kind": "active",
      "uid": "uid",
      "date": "2026-11-19",
      "month": 1,
      "day": 1,
      "weekday": 1,
      "position": 1,
      "easter_kind": "western",
      "easter_offset": 1,
      "observed": "none",
      "valid_from": "2026-11-19",
      "valid_to": "2026-11-19",
      "name_pt": "name pt",
      "name_en": "name en",
      "kind_of_day": "holiday",
      "area_id": "are_2ZTQYjrK63ZImD3sMz1O2BhWeZV",
      "source_ref": "source ref"
    }
  ],
  "changed": [
    {
      "kind": "active",
      "uid": "uid",
      "date": "2026-11-19",
      "month": 1,
      "day": 1,
      "weekday": 1,
      "position": 1,
      "easter_kind": "western",
      "easter_offset": 1,
      "observed": "none",
      "valid_from": "2026-11-19",
      "valid_to": "2026-11-19",
      "name_pt": "name pt",
      "name_en": "name en",
      "kind_of_day": "holiday",
      "area_id": "are_2ZTQYjrK63ZImD3sMz1O2BhWeZV",
      "source_ref": "source ref"
    }
  ],
  "removed": [
    {
      "kind": "active",
      "uid": "uid",
      "date": "2026-11-19",
      "month": 1,
      "day": 1,
      "weekday": 1,
      "position": 1,
      "easter_kind": "western",
      "easter_offset": 1,
      "observed": "none",
      "valid_from": "2026-11-19",
      "valid_to": "2026-11-19",
      "name_pt": "name pt",
      "name_en": "name en",
      "kind_of_day": "holiday",
      "area_id": "are_2ZTQYjrK63ZImD3sMz1O2BhWeZV",
      "source_ref": "source ref"
    }
  ],
  "conflicts": [
    {
      "date": "2026-11-19",
      "existing_kind": "holiday",
      "incoming_kind": "holiday",
      "detail": "detail"
    }
  ],
  "affected": [
    {
      "type": "active",
      "id": "cal_26gTtQiVPucb3CyVJaoRD6UlbOQ",
      "name": "Ana Matsinhe",
      "from": "2026-11-19T09:30:00Z",
      "to": "2026-11-19T09:30:00Z",
      "count": 1
    }
  ],
  "affected_limitations": [
    "affected limitation"
  ],
  "confirmed_by": "confirmed by",
  "outcome": "outcome",
  "created_at": "2026-11-19T09:30:00Z",
  "applied_at": "2026-11-19T09:30:00Z"
}

Apply a calendar import after its conflicts are resolved

Logs

POST /calendar/imports/{id}/apply

Writes a previewed import into the tenant calendar: added and changed rules are created or updated in place, and dated days replace any day with the same source reference. If the preview has conflicts, the import is marked failed and the call returns 409; an import that is no longer in preview status is returned unchanged, so repeating the call is safe. Returns 400 when the linked source has since been disabled. Requires automations:write.

Parameters

idstring · path · required

Id of the calendar import to apply (prefix cim); it must belong to the caller's tenant.

Returns

200 Applied import

Show attributes
idstring · optional
tenant_idstring · optional
source_idstring · optional
formatstring · optional

one of ics, csv

statusstring · optional

one of preview, applied, failed

itemsarray of CalendarImportItem · optional
Show child attributes
kindstring · optional
uidstring · optional
datestring (date) · optional
monthinteger · optional
dayinteger · optional
weekdayinteger · optional
positioninteger · optional
easter_kindstring · optional

one of western, orthodox

easter_offsetinteger · optional
observedstring · optional

one of none, next, previous, nearest

valid_fromstring (date) · optional
valid_tostring (date) · optional
name_ptstring · optional
name_enstring · optional
kind_of_daystring · optional

one of holiday, closure, working

area_idstring · optional
source_refstring · optional
addedarray of CalendarImportItem · optional
Show child attributes
kindstring · optional
uidstring · optional
datestring (date) · optional
monthinteger · optional
dayinteger · optional
weekdayinteger · optional
positioninteger · optional
easter_kindstring · optional

one of western, orthodox

easter_offsetinteger · optional
observedstring · optional

one of none, next, previous, nearest

valid_fromstring (date) · optional
valid_tostring (date) · optional
name_ptstring · optional
name_enstring · optional
kind_of_daystring · optional

one of holiday, closure, working

area_idstring · optional
source_refstring · optional
changedarray of CalendarImportItem · optional
Show child attributes
kindstring · optional
uidstring · optional
datestring (date) · optional
monthinteger · optional
dayinteger · optional
weekdayinteger · optional
positioninteger · optional
easter_kindstring · optional

one of western, orthodox

easter_offsetinteger · optional
observedstring · optional

one of none, next, previous, nearest

valid_fromstring (date) · optional
valid_tostring (date) · optional
name_ptstring · optional
name_enstring · optional
kind_of_daystring · optional

one of holiday, closure, working

area_idstring · optional
source_refstring · optional
removedarray of CalendarImportItem · optional
Show child attributes
kindstring · optional
uidstring · optional
datestring (date) · optional
monthinteger · optional
dayinteger · optional
weekdayinteger · optional
positioninteger · optional
easter_kindstring · optional

one of western, orthodox

easter_offsetinteger · optional
observedstring · optional

one of none, next, previous, nearest

valid_fromstring (date) · optional
valid_tostring (date) · optional
name_ptstring · optional
name_enstring · optional
kind_of_daystring · optional

one of holiday, closure, working

area_idstring · optional
source_refstring · optional
conflictsarray of object · optional
Show child attributes
datestring (date) · optional
existing_kindstring · optional

one of holiday, closure, working

incoming_kindstring · optional

one of holiday, closure, working

detailstring · optional
affectedarray of object · optional
Show child attributes
typestring · required
idstring · required
namestring · optional
fromstring (date-time) · optional
tostring (date-time) · optional
countinteger · required
affected_limitationsarray of string · optional

Consumer coverage gaps and date behaviors not recalculated by this preview.

confirmed_bystring · optional
outcomestring · optional
created_atstring (date-time) · optional
applied_atstring (date-time) · optional

Errors 409

Permissions automations:write · Roles: admin, finance, operations, owner

curl -X POST "$BUSINESS_API/calendar/imports/{id}/apply" \
  -H "Authorization: Bearer sk_test_..."
Response 200
{
  "id": "cal_26gTtQiVPucb3CyVJaoRD6UlbOQ",
  "tenant_id": "ten_2ugFXIC316WXzGu1HGal90AxTA6",
  "source_id": "sou_2fjWEpPCsLRCQBV64hz26xd8MF9",
  "format": "ics",
  "status": "preview",
  "items": [
    {
      "kind": "active",
      "uid": "uid",
      "date": "2026-11-19",
      "month": 1,
      "day": 1,
      "weekday": 1,
      "position": 1,
      "easter_kind": "western",
      "easter_offset": 1,
      "observed": "none",
      "valid_from": "2026-11-19",
      "valid_to": "2026-11-19",
      "name_pt": "name pt",
      "name_en": "name en",
      "kind_of_day": "holiday",
      "area_id": "are_2ZTQYjrK63ZImD3sMz1O2BhWeZV",
      "source_ref": "source ref"
    }
  ],
  "added": [
    {
      "kind": "active",
      "uid": "uid",
      "date": "2026-11-19",
      "month": 1,
      "day": 1,
      "weekday": 1,
      "position": 1,
      "easter_kind": "western",
      "easter_offset": 1,
      "observed": "none",
      "valid_from": "2026-11-19",
      "valid_to": "2026-11-19",
      "name_pt": "name pt",
      "name_en": "name en",
      "kind_of_day": "holiday",
      "area_id": "are_2ZTQYjrK63ZImD3sMz1O2BhWeZV",
      "source_ref": "source ref"
    }
  ],
  "changed": [
    {
      "kind": "active",
      "uid": "uid",
      "date": "2026-11-19",
      "month": 1,
      "day": 1,
      "weekday": 1,
      "position": 1,
      "easter_kind": "western",
      "easter_offset": 1,
      "observed": "none",
      "valid_from": "2026-11-19",
      "valid_to": "2026-11-19",
      "name_pt": "name pt",
      "name_en": "name en",
      "kind_of_day": "holiday",
      "area_id": "are_2ZTQYjrK63ZImD3sMz1O2BhWeZV",
      "source_ref": "source ref"
    }
  ],
  "removed": [
    {
      "kind": "active",
      "uid": "uid",
      "date": "2026-11-19",
      "month": 1,
      "day": 1,
      "weekday": 1,
      "position": 1,
      "easter_kind": "western",
      "easter_offset": 1,
      "observed": "none",
      "valid_from": "2026-11-19",
      "valid_to": "2026-11-19",
      "name_pt": "name pt",
      "name_en": "name en",
      "kind_of_day": "holiday",
      "area_id": "are_2ZTQYjrK63ZImD3sMz1O2BhWeZV",
      "source_ref": "source ref"
    }
  ],
  "conflicts": [
    {
      "date": "2026-11-19",
      "existing_kind": "holiday",
      "incoming_kind": "holiday",
      "detail": "detail"
    }
  ],
  "affected": [
    {
      "type": "active",
      "id": "cal_26gTtQiVPucb3CyVJaoRD6UlbOQ",
      "name": "Ana Matsinhe",
      "from": "2026-11-19T09:30:00Z",
      "to": "2026-11-19T09:30:00Z",
      "count": 1
    }
  ],
  "affected_limitations": [
    "affected limitation"
  ],
  "confirmed_by": "confirmed by",
  "outcome": "outcome",
  "created_at": "2026-11-19T09:30:00Z",
  "applied_at": "2026-11-19T09:30:00Z"
}