Shifts

Shifts are the building blocks of your roster — each one ties a time, a site, a staff member, and the participants being supported into a single rostered booking. On this page you'll find the shift model, the endpoint for listing published shifts across a date range, and the endpoint for retrieving a single shift. Reading shifts requires the read:roster_export scope.

Only published shifts are returned. Draft and unpublished shifts are an editor-facing concern and never appear on the public API. Sensitive free-text (adminNotes, exitNotes) is also never exposed — only the participant-facing information note is returned.

The shift model

The shift model contains the scheduling details of a single rostered booking. Like every Diversity Sync resource, a shift carries an object discriminator and a livemode flag, and nullable scalars are always present (as null) rather than omitted.

Properties

Name
object
Type
string
Description
The string shift. Identifies the type of this object.
Name
id
Type
integer
Description
Unique identifier for the shift within your organisation.
Name
start
Type
string
Description
Scheduled start, as an ISO 8601 UTC timestamp (e.g. 2026-06-02T09:00:00Z).
Name
end
Type
string
Description
Scheduled end, as an ISO 8601 UTC timestamp.
Name
status
Type
string
Description
The shift's status — one of Scheduled, In Progress, On Break, or Complete.
Name
type
Type
string
Description
The shift type (e.g. standard, sleepover, leave).
Name
category
Type
string
Description
The shift category configured for your organisation.
Name
site
Type
object
Description
The site the shift is at, as { id, name }, or null if unassigned.
Name
staff
Type
object
Description
The assigned staff member, as { id, name }, or null for an open shift.
Name
role
Type
string
Description
The shift role name, or null if no role is set.
Name
participants
Type
array
Description
The participants on the shift, each as { id, name }. Row-level access controlled — see the note below.
Name
hours
Type
number
Description
Rostered duration in hours, less unpaid breaks. Permission-gated: this field is omitted entirely unless the key also holds the read:roster_hours scope (this is distinct from a present-but-null value).
Name
livemode
Type
boolean
Description
true when the object was created with a live key (ds_live_…), false for a test key.

Participants are row-level access controlled. Unless the key holds the write:participants_admin scope, only the participants the shift's staff member can access appear in the participants array — exactly as in the Diversity Sync app. This prevents participant-name enumeration via the roster surface.

GET/v1/shifts

List shifts

Returns a paginated list of published shifts, ordered by start time (most recent first). Requires the read:roster_export scope. Narrow the result with the optional filters below — a from/to window is the typical way to export a fortnight of roster.

The response is the canonical list envelope: an object with object: "list", the url of the resource, a has_more boolean, and a data array of shift objects.

Optional attributes

Name
from
Type
string
Description
Only include shifts starting at or after this ISO 8601 datetime (UTC).
Name
to
Type
string
Description
Only include shifts starting before this ISO 8601 datetime (UTC).
Name
siteId
Type
integer
Description
Only include shifts at this site.
Name
staffId
Type
integer
Description
Only include shifts assigned to this staff member.
Name
status
Type
string
Description
Only include shifts with this status — one of Scheduled, In Progress, On Break, or Complete. Any other value returns a 400.
Name
limit
Type
integer
Description
The maximum number of shifts to return, 1–100. Defaults to 25.
Name
starting_after
Type
integer
Description
A cursor for pagination. Pass the id of the last shift from the previous page to fetch the next page.

Request

GET

/v1/shifts

curl -G https://api.diversitysync.com/v1/shifts \
  -H "Authorization: Bearer {access_token}" \
  -d from=2026-06-01T00:00:00Z \
  -d to=2026-06-15T00:00:00Z \
  -d limit=25

Response

{
  "object": "list",
  "url": "/v1/shifts",
  "has_more": true,
  "data": [
    {
      "object": "shift",
      "id": 90213,
      "start": "2026-06-02T09:00:00Z",
      "end": "2026-06-02T17:00:00Z",
      "status": "Scheduled",
      "type": "standard",
      "category": "Community Access",
      "site": { "id": 12, "name": "Northside House" },
      "staff": { "id": 482, "name": "Jordan Avery" },
      "role": "Support Worker",
      "participants": [
        { "id": 1043, "name": "Riley Chen" }
      ],
      "hours": 7.5,
      "livemode": true
    }
  ]
}

hours appears above only because the key also holds the read:roster_hours scope. Without it, the field is omitted from every shift object.

GET/v1/shifts/{id}

Retrieve a shift

Retrieves a single published shift by its id, with additional detail not present in the list view — clock times, break minutes, cancellation reason, leave type, and the participant-facing information note. Requires the read:roster_export scope.

Unlike the list endpoint, this returns the shift object at the top level — it is not wrapped in an envelope. Returns a 404 with resource_missing if no published shift with that id exists in your organisation.

Additional properties

Name
clockedStart
Type
string
Description
When the staff member actually clocked on, as an ISO 8601 UTC timestamp, or null if they haven't.
Name
clockedEnd
Type
string
Description
When the staff member actually clocked off, as an ISO 8601 UTC timestamp, or null if they haven't.
Name
breakMinutes
Type
integer
Description
Unpaid break length in minutes, or null if not recorded.
Name
cancellation
Type
string
Description
The cancellation reason, or null if the shift was not cancelled.
Name
reviewed
Type
boolean
Description
Whether the shift has been reviewed.
Name
information
Type
string
Description
The participant-facing information note attached to the shift, or null.
Name
leaveType
Type
string
Description
The leave type name for shifts that represent leave, or null.

Request

GET

/v1/shifts/{id}

curl https://api.diversitysync.com/v1/shifts/90213 \
  -H "Authorization: Bearer {access_token}"

Response

{
  "object": "shift",
  "id": 90213,
  "start": "2026-06-02T09:00:00Z",
  "end": "2026-06-02T17:00:00Z",
  "clockedStart": "2026-06-02T09:02:11Z",
  "clockedEnd": "2026-06-02T17:00:46Z",
  "breakMinutes": 30,
  "status": "Complete",
  "type": "standard",
  "category": "Community Access",
  "cancellation": null,
  "reviewed": true,
  "information": "Pick up from day program at 9.",
  "hours": 7.5,
  "site": { "id": 12, "name": "Northside House" },
  "staff": { "id": 482, "name": "Jordan Avery" },
  "role": "Support Worker",
  "leaveType": null,
  "participants": [
    { "id": 1043, "name": "Riley Chen" }
  ],
  "livemode": true
}

Every response includes a Request-Id header (quote it to support when reporting an issue) and Diversity-Sync-Version: v1. Responses under /v1 also carry RateLimit-Limit, RateLimit-Remaining, and RateLimit-Reset headers — /v1 is limited to 120 requests per minute per API key. Over the limit you'll get a 429 with Retry-After and a rate_limit_error. See Errors for the full error object.