Scheduled Windows - Fields & Syntax

The purpose of this document is to help explain the syntax of the fields used in our Scheduled Windows feature.

The logic behind scheduling the windows is based on iCalendar’s RRule spec (RRule standing for recurrence rule, that’s not a typo).

Due to UI constraints, we will only be supporting a subset of RRule options. There are two types of exclusion windows that a user can create, a recurring window and a one-time window.

For reference, here is an example POST request body for a recurring window:

{
  "window_type": "exclude",
  "window_name": "Recurring window example",
  "window_description": "made via swagger",
  "org_uuid": "fa0efcda-9a97-4a84-a753-33008037715e",
  "rrule": "FREQ=YEARLY;BYMONTH=1,4;BYDAY=+1TU,+1WE,+3TU,+3WE",
  "duration_minutes": 60,
  "dtstart": "2025-09-18T09:00:00.000Z",
  "use_local_tz": false,
  "group_uuids": [
    "0760c581-96ef-4770-8f9b-db2000c0d832"
  ],
  "recurrence": "recurring",
  "status": "active"
}

Recurring Windows

Recurring windows have three components to their schedule: the dtstart, the rrule, and the duration_minutes fields.

• recurrence: recurring
• dtstart: required - ISO 8601 format - this is the beginning of the window series. The start time will be used in every recurrence. This time must be in UTC so the Z is required. (All dates and times are in UTC for this feature.)
• rrule: The recurrence pattern. This is the field that has limited support for rrule options. For a recurring rule it MUST be:
  • FREQ=YEARLY required - only yearly is supported
  • BYMONTH= required - comma separated list of month numbers, 1 based (January === 1)
  • BYDAY= required - comma separated list of the occurrence and the rrule weekday constant. The “occurrence” is the first, second, third, fourth, or fifth occurrence of that weekday in the month. Patch Tuesday, for example, would be +2TU . Valid occurrences are 1 through 5 only. Valid weekdays are based on the rrule constants (MO, TU, WE, TH, FR, SA, SU). The example provided in the POST request body "BYDAY=+1TU,+1WE,+3TU,+3WE" corresponds to the first and third Tuesday and Wednesday of the month.
• duration_minutes: required - limit 1440, which is 24 hours represented as minutes. Two hours would be 120.

One Time Windows

One time windows allow the user to schedule a single occurrence, but that single occurrence may span multiple days. It’s composed of different required fields than the recurring window.

For reference, here is the POST request body for a one-time window:

{
  "window_type": "exclude",
  "window_name": "One Time",
  "window_description": "made via swagger",
  "org_uuid": "fa0efcda-9a97-4a84-a753-33008037715e",
  "rrule": "FREQ=DAILY;UNTIL=20250917T100000Z",
  "dtstart": "2025-09-17T09:00:00.000Z",
  "use_local_tz": false,
  "group_uuids": [
    "0760c581-96ef-4770-8f9b-db2000c0d832"
  ],
  "recurrence": "once",
  "status": "active"
}

One-time windows have two components to their schedule, the dtstart and the rrule fields.

• recurrence: once
• dtstart: required - ISO 8601 format - this is the beginning of the window start. This time is in UTC, so the Z is required. ( All dates and times are in UTC. )
• rrule: The recurrence pattern. This is the field that has limited support for rrule options. For a one time rule it MUST be:
  • FREQ=DAILY required - only daily supported
  • UNTIL= required - compact ISO 8601 format, again in UTC. No separators but the T and Z are still required. This date time string represents the end of the occurrence.

A window with a dtstart of 2025-09-18T09:00:00.000Z and an UNTIL=20250918T100000Z will run from 9 am to 10 am on Sept 18 UTC.

Other Required Fields

This API may support future functionality, so to support this we have two fields that are required but only accept specific values:

• window_type: "exclude"
• use_local_tz: false
• window_name Give your window a meaningful name.
• org_uuid is a required path parameter.