Schedules (legacy)

📘
New Schedules endpoints are now available
Schedules legacy endpoints will continue to be supported. Any deprecation will be communicated with a minimum 6-month notice. See Schedules to get started.

Schedules endpoints allow you to assign recurring inspections to users or groups on a defined cadence. Each schedule item links a template, one or more assignees, a recurrence rule, and optional reminders.

Schedule item format

The following fields are returned on all schedule item read responses.

{ "id": "31d302e2-6f49-435f-944e-be8276f284b6", "type": "USER", "name": "Joe Bloggs" }
The following fields are returned on all schedule item read responses.

```json
{
  "id": "87894eeb-ee76-4551-b3ab-0c60c675d820",
  "description": "Workplace Reopening Checklist - Every day",
  "must_complete": "ONE",
  "can_late_submit": true,
  "recurrence": "RRULE:INTERVAL=1;FREQ=DAILY;DTSTART=20210803T210000Z",
  "start_time": { "hour": 9, "minute": 0 },
  "duration": "PT8H",
  "timezone": "Pacific/Auckland",
  "from_date": "2021-08-02T21:00:00Z",
  "to_date": null,
  "reminders": [{ "event": "START", "duration": "P0D" }],
  "status": "ACTIVE",
  "assignees": [
    { "id": "87894eeb-ee76-4551-b3ab-0c60c675d820", "type": "ROLE", "name": "Joe's Team" }
  ],
  "creator": {
    "id": "83224e56-ad58-4e19-b633-fde5271ac8e4", "type": "USER", "name": "Joe Bloggs"
  },
  "document": {
    "id": "dfa57152-4164-4534-90b4-4992f65630a0", "type": "TEMPLATE", "name": "Workplace Reopening Checklist"
  },
  "location_id": null,
  "next_occurrence": {
    "start": "2021-08-09T21:00:00Z",
    "due": "2021-08-10T05:00:00Z"
  },
  "modified_at": "2021-08-10T00:09:50.488Z",
  "created_at": "2021-08-10T00:09:50.488Z"
}

Field	Type	Description
`id`	String (UUID)	Unique ID of the schedule item.
`description`	String	Human-readable label for the schedule item.
`must_complete`	String	Completion requirement. `ONE` = any one assignee must complete. `ALL` = every assignee must complete.
`can_late_submit`	Boolean	When `true`, assignees can submit the inspection after the due date has passed.
`recurrence`	String (RRule)	Recurrence rule in RRule format. Controls how often occurrences are generated.
`start_time`	Object	Time of day each occurrence starts, expressed as `{ "hour": 0–23, "minute": 0–59 }` in the schedule's `timezone`.
`duration`	String (ISO 8601)	How long after `start_time` an assignee can still begin the inspection. Example: `PT8H` = 8 hours.
`timezone`	String (IANA)	Timezone used to interpret `start_time`. Example: `Pacific/Auckland`.
`from_date`	String (ISO 8601)	Date and time the schedule item becomes active.
`to_date`	String (ISO 8601) or `null`	Date and time the schedule item ends. `null` means no end date.
`reminders`	Array of objects	Reminders sent to assignees. See Reminders.
`status`	String	Current status of the schedule item. See Statuses. Read-only.
`assignees`	Array of objects	Users or groups assigned to this schedule item. See Entity object.
`creator`	Object	User who created this schedule item. See Entity object. Read-only.
`document`	Object	Template assigned to this schedule item. See Document object.
`location_id`	String (UUID) or `null`	ID of the site assigned to this schedule item.
`next_occurrence`	Object or `null`	Start and due times for the next scheduled occurrence. `null` when status is `FINISHED`. See Occurrence object. Read-only.
`modified_at`	String (ISO 8601)	Last modified timestamp. Read-only.
`created_at`	String (ISO 8601)	Creation timestamp. Read-only.

Entity object

Represents a user or group (role).

{ "id": "31d302e2-6f49-435f-944e-be8276f284b6", "type": "USER", "name": "Joe Bloggs" }

Field	Type	Description
`id`	String (UUID)	ID of the user or group.
`type`	String	`USER` for an individual user. `ROLE` for a group.
`name`	String	Display name. Present in read responses; not required on write.

Document object

Represents the template linked to a schedule item.

{ "id": "dfa57152-4164-4534-90b4-4992f65630a0", "type": "TEMPLATE", "name": "Workplace Reopening Checklist" }

Field	Type	Description
`id`	String (UUID)	ID of the template.
`type`	String	Always `TEMPLATE`.
`name`	String	Template name. Present in read responses; not required on write.

Occurrence object

Present on read responses only. null when the schedule is FINISHED or has no future occurrences.

{ "start": "2021-08-09T21:00:00Z", "due": "2021-08-10T05:00:00Z" }

Field	Type	Description
`start`	String (ISO 8601)	UTC datetime when the next occurrence begins.
`due`	String (ISO 8601)	UTC datetime when the next occurrence expires. Calculated as `start` + `duration`.

Reminder object

{ "event": "START", "duration": "P0D" }

Field	Type	Description
`event`	String	The event that triggers the reminder. `START` = occurrence start time. `DUE` = occurrence due time.
`duration`	String (ISO 8601)	How long before the event to send the reminder. Use `P0D` to send the reminder at the time of the event. Example: `PT30M` = 30 minutes before.

Statuses

Value	Description
`ACTIVE`	The schedule item is running and will generate occurrences. Default on creation.
`PAUSED`	The schedule item is paused. Occurrences are not generated.
`NO_TEMPLATE`	The linked template has been deleted or archived.
`NO_ASSIGNEE`	No valid assignees remain for this schedule item.
`FINISHED`	The schedule item has reached its `to_date` or occurrence count limit.