---
title: "Fetch schedules"
method: GET
path: "/schedules"
tags: ["Schedules"]
---

# Fetch schedules

`GET /schedules`

The schedule resource represents a simplified calendar event or event generation rule, and may be used to configure time based functionality:

- When access is allowed or restricted ("time restrictions"), set `consequence` to `allow`
- When elevator stops are kept accessible ("permit timer"), set `consequence` to `permit`
- When locks are kept unlocked ("unlock timer"), set `consequence` to `unlock`
- To override an allow, permit or unlock, set `override` to `true`. The schedule will then neutralize events of other schedules of the same consequence.

Possible consequences for locks:
  - allow
  - unlock

Possible consequences for elevator stops:
  - allow
  - permit

Possible consequences for elevator groups:
  - allow

There are four types of schedules:

- Holiday calendar: events that are interpreted based on a region's holiday rules
- Recurring event: events that are interpreted based on the current weekday based on the time zone of the place they are added to
- Single event: an event that starts and ends on specific date times regardless of time zone
- Single all day event: events that are interpreted based on the time zone of the place they're added to

The API makes a few assumptions:

- If `region` or `observed` are set, schedules are treated as holiday calendars
- If `starts_at` or `ends_at` are set, events are treated as single events
- If `starts_at_date` or `ends_at_date` are set, events are treated as single all day events
- Else, events are treated as recurring events

Validations:

- Holiday calendars require both `region` and `observed` to be set
- Single events require both `starts_at` and `ends_at` as RFC3339 timestamps
- Single events require both `starts_at` and `ends_at` as RFC3339 timestamps
- Single all day events require both `starts_at_date` and `ends_at_date` in the `YYYY-MM-DD` format
- Recurring events require at least one weekday, and may specify `starts_at_time` and `ends_at_time` in the `hh:mm` format
- Starting dates/times must be before ending dates/times

The difference between single events and all day events are that single events are absolute, i.e. independent of
the time zone of the place. Single all day events carry no time zone information but are always interpreted based
on the time zone of the place.

Note that holidays are interpreted relative to a time zone. It is therefore possible to specify e.g. US observances for a location in Europe.

## Query parameters

- `ids` string
- `limit` integer
- `offset` integer
- `consequence` 'allow' | 'first_to_arrive' | 'permit' | 'unlock'
- `scheduleable_type` 'Group' | 'Lock' | 'ElevatorStop'
- `scheduleable_id` integer

## Response `200`

OK

- union[]
  - union
    - object
      - `id` integer, required — The ID of the schedule
      - `resource_type` 'Schedule', required — The resource type of the schedule
      - `created_at` string, date-time, required — When the schedule was created
      - `updated_at` string, date-time, required — When the schedule was updated
      - `name` string, nullable, required — The name of the schedule
      - `enabled` boolean, required — Whether the schedule is enabled
      - `override` boolean, required — Whether to override other events of the same consequence
      - `consequence` 'allow' | 'first_to_arrive' | 'permit' | 'unlock', required — Defines what happens to the `scheduleable` when the schedule is occuring. The `unlock` value only applies to schedules with `scheduleable_type` set to `Lock`. The `permit` value only applies to schedules with `scheduleable_type` set to `ElevatorStop`.
      - `scheduleable_type` 'Group' | 'Lock' | 'ElevatorStop', required — The type of the schedulable
      - `scheduleable_id` integer, required — The ID of the schedulable
      - `scheduleable` object, required
        - `id` integer, required — The ID of the schedulable
        - `type` 'Group' | 'Lock' | 'ElevatorStop', required — The type of the schedulable
        - `name` string, required — The name of the schedulable
      - `place_id` integer, nullable, required — The place ID of the schedule
      - `place` object — The place of the schedule
        - `id` integer, required — The ID of the place
        - `resource_type` 'Place', required — The resource type of the place
        - `name` string, required — The name of the place
      - `integration_id` integer, nullable, required — The integration ID of the schedule
      - `type` 'holiday_calendar', required — The type of the schedule
      - `region` 'ar' | 'at' | 'au' | 'au_act' | 'au_nsw' | 'au_nt' | 'au_qld' | 'au_sa' | 'au_tas' | 'au_vic' | 'au_wa' | 'bg' | 'br' | 'by' | 'ca' | 'ca_ab' | 'ca_bc' | 'ca_mb' | 'ca_nb' | 'ca_nl' | 'ca_ns' | 'ca_nt' | 'ca_nu' | 'ca_on' | 'ca_pe' | 'ca_qc' | 'ca_sk' | 'ca_yt' | 'ch' | 'ch_ag' | 'ch_ai' | 'ch_ar' | 'ch_be' | 'ch_bl' | 'ch_bs' | 'ch_fr' | 'ch_ge' | 'ch_gl' | 'ch_gr' | 'ch_ju' | 'ch_lu' | 'ch_ne' | 'ch_nw' | 'ch_ow' | 'ch_sg' | 'ch_sh' | 'ch_so' | 'ch_sz' | 'ch_tg' | 'ch_ti' | 'ch_ur' | 'ch_vd' | 'ch_vs' | 'ch_zg' | 'ch_zh' | 'cl' | 'co' | 'cr' | 'cy' | 'cz' | 'de' | 'de_bb' | 'de_be' | 'de_bw' | 'de_by' | 'de_hb' | 'de_he' | 'de_hh' | 'de_mv' | 'de_ni' | 'de_nw' | 'de_rp' | 'de_sh' | 'de_sl' | 'de_sn' | 'de_st' | 'de_th' | 'dk' | 'ee' | 'es' | 'es_an' | 'es_ar' | 'es_ce' | 'es_cl' | 'es_cm' | 'es_cn' | 'es_ct' | 'es_ex' | 'es_ga' | 'es_ib' | 'es_lo' | 'es_m' | 'es_mu' | 'es_na' | 'es_o' | 'es_pv' | 'es_v' | 'es_vc' | 'fi' | 'fr' | 'gb' | 'gb_con' | 'gb_eng' | 'gb_nir' | 'gb_sct' | 'gb_wls' | 'ge' | 'gr' | 'hk' | 'hr' | 'hu' | 'ie' | 'il' | 'in' | 'in_ap' | 'in_ar' | 'in_as' | 'in_br' | 'in_cg' | 'in_ga' | 'in_gj' | 'in_hp' | 'in_hr' | 'in_jh' | 'in_jk' | 'in_ka' | 'in_kl' | 'in_mh' | 'in_mp' | 'in_mz' | 'in_nl' | 'in_od' | 'in_pb' | 'in_py' | 'in_sk' | 'in_tr' | 'in_ts' | 'in_wb' | 'is' | 'it' | 'it_bl' | 'it_fi' | 'it_ge' | 'it_pd' | 'it_rm' | 'it_ro' | 'it_to' | 'it_tv' | 'it_ve' | 'it_vi' | 'it_vr' | 'jp' | 'ke' | 'kr' | 'kz' | 'li' | 'lt' | 'lu' | 'lv' | 'ma' | 'mc' | 'mx' | 'mx_pue' | 'my' | 'ng' | 'nl' | 'no' | 'nz' | 'pe' | 'ph' | 'pl' | 'pt' | 'ro' | 'ru' | 'se' | 'sg' | 'th' | 'tn' | 'tr' | 'ua' | 'us' | 'us_ak' | 'us_al' | 'us_ar' | 'us_az' | 'us_ca' | 'us_co' | 'us_ct' | 'us_dc' | 'us_de' | 'us_fl' | 'us_ga' | 'us_gu' | 'us_hi' | 'us_ia' | 'us_id' | 'us_il' | 'us_in' | 'us_ks' | 'us_ky' | 'us_la' | 'us_ma' | 'us_md' | 'us_me' | 'us_mi' | 'us_mn' | 'us_mo' | 'us_ms' | 'us_mt' | 'us_nc' | 'us_nd' | 'us_ne' | 'us_nh' | 'us_nj' | 'us_nm' | 'us_nv' | 'us_ny' | 'us_oh' | 'us_ok' | 'us_or' | 'us_pa' | 'us_pr' | 'us_ri' | 'us_sc' | 'us_sd' | 'us_tn' | 'us_tx' | 'us_ut' | 'us_va' | 'us_vi' | 'us_vt' | 'us_wa' | 'us_wi' | 'us_wv' | 'us_wy' | 'vn' | 'za', required — Which region's holiday rules to follow for event generation. For details on regions, see the holiday calendar endpoint for regions.
      - `observed` boolean, required — Whether the events should consider observances
      - `ignored_holidays` string[], required — The names of ignored holidays
      - `holidays` object[], required
        - `date` string, date, required — When the next holiday occurs
        - `name` string, required — The name of the next holiday
    - object
      - `id` integer, required — The ID of the schedule
      - `resource_type` 'Schedule', required — The resource type of the schedule
      - `created_at` string, date-time, required — When the schedule was created
      - `updated_at` string, date-time, required — When the schedule was updated
      - `name` string, nullable, required — The name of the schedule
      - `enabled` boolean, required — Whether the schedule is enabled
      - `override` boolean, required — Whether to override other events of the same consequence
      - `consequence` 'allow' | 'first_to_arrive' | 'permit' | 'unlock', required — Defines what happens to the `scheduleable` when the schedule is occuring. The `unlock` value only applies to schedules with `scheduleable_type` set to `Lock`. The `permit` value only applies to schedules with `scheduleable_type` set to `ElevatorStop`.
      - `scheduleable_type` 'Group' | 'Lock' | 'ElevatorStop', required — The type of the schedulable
      - `scheduleable_id` integer, required — The ID of the schedulable
      - `scheduleable` object, required
        - `id` integer, required — The ID of the schedulable
        - `type` 'Group' | 'Lock' | 'ElevatorStop', required — The type of the schedulable
        - `name` string, required — The name of the schedulable
      - `place_id` integer, nullable, required — The place ID of the schedule
      - `place` object — The place of the schedule
        - `id` integer, required — The ID of the place
        - `resource_type` 'Place', required — The resource type of the place
        - `name` string, required — The name of the place
      - `integration_id` integer, nullable, required — The integration ID of the schedule
      - `type` 'recurring_event', required — The type of the schedule
      - `monday` boolean, required — Whether the schedule occurs on this day
      - `tuesday` boolean, required — Whether the schedule occurs on this day
      - `wednesday` boolean, required — Whether the schedule occurs on this day
      - `thursday` boolean, required — Whether the schedule occurs on this day
      - `friday` boolean, required — Whether the schedule occurs on this day
      - `saturday` boolean, required — Whether the schedule occurs on this day
      - `sunday` boolean, required — Whether the schedule occurs on this day
      - `starts_at_time` string, required — When the schedule starts at, in the `hh:mm` format
      - `ends_at_time` string, required — When the schedule ends at, in the `hh:mm` format
      - `next_occurence` object, required
        - `starts_at` string, date-time, required — When the next event starts at
        - `ends_at` string, date-time, required — When the next event ends at
    - object
      - `id` integer, required — The ID of the schedule
      - `resource_type` 'Schedule', required — The resource type of the schedule
      - `created_at` string, date-time, required — When the schedule was created
      - `updated_at` string, date-time, required — When the schedule was updated
      - `name` string, nullable, required — The name of the schedule
      - `enabled` boolean, required — Whether the schedule is enabled
      - `override` boolean, required — Whether to override other events of the same consequence
      - `consequence` 'allow' | 'first_to_arrive' | 'permit' | 'unlock', required — Defines what happens to the `scheduleable` when the schedule is occuring. The `unlock` value only applies to schedules with `scheduleable_type` set to `Lock`. The `permit` value only applies to schedules with `scheduleable_type` set to `ElevatorStop`.
      - `scheduleable_type` 'Group' | 'Lock' | 'ElevatorStop', required — The type of the schedulable
      - `scheduleable_id` integer, required — The ID of the schedulable
      - `scheduleable` object, required
        - `id` integer, required — The ID of the schedulable
        - `type` 'Group' | 'Lock' | 'ElevatorStop', required — The type of the schedulable
        - `name` string, required — The name of the schedulable
      - `place_id` integer, nullable, required — The place ID of the schedule
      - `place` object — The place of the schedule
        - `id` integer, required — The ID of the place
        - `resource_type` 'Place', required — The resource type of the place
        - `name` string, required — The name of the place
      - `integration_id` integer, nullable, required — The integration ID of the schedule
      - `type` 'single_all_day_event', required — The type of the schedule
      - `starts_at_date` string, date, required — When the schedule starts at
      - `ends_at_date` string, date, required — When the schedule ends at
    - object
      - `id` integer, required — The ID of the schedule
      - `resource_type` 'Schedule', required — The resource type of the schedule
      - `created_at` string, date-time, required — When the schedule was created
      - `updated_at` string, date-time, required — When the schedule was updated
      - `name` string, nullable, required — The name of the schedule
      - `enabled` boolean, required — Whether the schedule is enabled
      - `override` boolean, required — Whether to override other events of the same consequence
      - `consequence` 'allow' | 'first_to_arrive' | 'permit' | 'unlock', required — Defines what happens to the `scheduleable` when the schedule is occuring. The `unlock` value only applies to schedules with `scheduleable_type` set to `Lock`. The `permit` value only applies to schedules with `scheduleable_type` set to `ElevatorStop`.
      - `scheduleable_type` 'Group' | 'Lock' | 'ElevatorStop', required — The type of the schedulable
      - `scheduleable_id` integer, required — The ID of the schedulable
      - `scheduleable` object, required
        - `id` integer, required — The ID of the schedulable
        - `type` 'Group' | 'Lock' | 'ElevatorStop', required — The type of the schedulable
        - `name` string, required — The name of the schedulable
      - `place_id` integer, nullable, required — The place ID of the schedule
      - `place` object — The place of the schedule
        - `id` integer, required — The ID of the place
        - `resource_type` 'Place', required — The resource type of the place
        - `name` string, required — The name of the place
      - `integration_id` integer, nullable, required — The integration ID of the schedule
      - `type` 'single_event', required — The type of the schedule
      - `starts_at` string, date-time, required — When the schedule starts at. Seconds are ignored.
      - `ends_at` string, date-time, required — When the schedule ends at. Seconds are ignored.

## Other responses

- `401` — Unauthorized

---

[API](https://skmtc.dev/kisi/apis/kisi-api.md) · [All operations](https://skmtc.dev/kisi/apis/kisi-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/kisi/kisi-api/revisions/998700ffff5a/schema)