Calendar: Calendar

Base URL: $BUSINESS_API

Get calendar

Logs

GET /calendar

Read the tenant's time zone, working week and template adoption

Returns the tenant-wide working calendar: time zone, working weekdays (0 = Sunday to 6 = Saturday) and the holiday template it follows, if any. When the tenant has never saved a calendar, the response is the built-in default (the default time zone and Monday to Friday) rather than a 404. Requires the automations:read permission.

Returns

200 Tenant calendar

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

curl -X GET "$BUSINESS_API/calendar" \
  -H "Authorization: Bearer sk_test_..."
Response 200

Tenant calendar

Update calendar

Logs

PUT /calendar

Set the tenant's time zone, working days and holiday template

Saves the calendar that billing due dates, grace periods and scheduled automations are evaluated against. An empty timezone keeps the current one and an omitted working_days keeps the current weekdays, but template_key and template_version are always replaced by the values sent, so omitting them detaches the calendar from its template; sending area_id saves a separate calendar for that service area. Returns 400 for an unknown IANA time zone or for working_days with more than seven entries or values outside 0-6. Requires automations:write.

Body application/json

timezonestring · optional
working_daysarray of integer · optional
template_keystring · optional
template_yearinteger · optional
area_idstring · optional

Returns

200 Updated calendar

Errors 400

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

curl -X PUT "$BUSINESS_API/calendar" \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{
  "timezone": "Africa/Maputo",
  "working_days": [
    0
  ],
  "template_key": "mz",
  "template_year": 1,
  "area_id": "are_2ZTQYjrK63ZImD3sMz1O2BhWeZV"
}'
Response 200

Updated calendar

Evaluate a schedule expression for previews

Logs

POST /calendar/occurrences

Dry-runs a schedule spec against the tenant calendar and returns its next run times, the same way billing and automations evaluate it, so a rule can be checked before it is saved. The calculation uses the area's calendar (or the tenant-wide one), its working weekdays, dated days, recurring rules and template, looking three years each way around after. count defaults to 5 and is capped at 50, and after defaults to now; an invalid spec returns 400. Requires automations:read.

Body application/json

specobject · required
afterstring (date-time) · optional
countinteger · optional
area_idstring · optional

Returns

200 Next occurrences

Errors 400

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

curl -X POST "$BUSINESS_API/calendar/occurrences" \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{
  "spec": {},
  "after": "2026-11-19T09:30:00Z",
  "count": 1,
  "area_id": "are_2ZTQYjrK63ZImD3sMz1O2BhWeZV"
}'
Response 200

Next occurrences

Export the effective calendar as iCalendar

Logs

GET /calendar/export.ics

Downloads the tenant's calendar as an iCalendar file (text/calendar attachment) that calendar applications can subscribe to or import. Each dated day becomes an all-day VEVENT, and each recurring rule becomes a VEVENT with a yearly RRULE (BYMONTH with BYMONTHDAY or BYDAY); Easter-relative rules use a non-standard EASTER/OFFSET RRULE that other applications may not understand. Event names use the Portuguese name. Requires automations:read.

Returns

200 iCalendar document

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

curl -X GET "$BUSINESS_API/calendar/export.ics" \
  -H "Authorization: Bearer sk_test_..."
Response 200

iCalendar document

Export the effective calendar as CSV

Logs

GET /calendar/export.csv

Downloads every dated day and recurring rule of the tenant as a CSV attachment (text/csv) for review or re-import. The header is date,rule,kind,name_pt,name_en,area,observed,source_reference: day rows fill the date column, and rule rows fill the rule column with semicolon-separated kind, month, day, weekday, position, easter and easter_offset values. All areas are included. Requires automations:read.

Returns

200 CSV document

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

curl -X GET "$BUSINESS_API/calendar/export.csv" \
  -H "Authorization: Bearer sk_test_..."
Response 200

CSV document