Shift notes

Shift notes are the timeline of contributions staff record against a participant — a free-text note, a submitted form, or an attachment, captured during or after a shift. On this page you'll find the shift note model and the endpoint for listing timeline items. Reading shift notes requires the read:notes scope.

Shift note content is sensitive care information. Holding read:notes does not bypass per-participant access control — results are still filtered to the participants the key's tied staff member can access, exactly as in the Diversity Sync app. The scope only waives the in-app 48-hour-shift rule, so notes outside that window become reachable; it never widens which participants you can see. Note that the field and form values of a submission are never exposed — only that a form is present. Grant this scope only to keys that genuinely need it.

The shift note model

Each shift note is a single contribution on a participant's timeline.

Properties

Name
object
Type
string
Description
The object type. Always shift_note.
Name
id
Type
integer
Description
Unique identifier for the shift note item within your organisation.
Name
ref
Type
string
Description
Stable reference for the item, safe to store on your side.
Name
timestamp
Type
string
Description
When the note applies to, as an ISO 8601 UTC timestamp.
Name
participant
Type
object
Description
The participant the note is about, as { id, name }.
Name
staff
Type
object
Description
The staff member who recorded the note, as { id, name }.
Name
shiftId
Type
integer
Description
The shift this note was recorded against, or null if it wasn't tied to a shift.
Name
content
Type
string
Description
The free-text note body, or null when the contribution carries no note text or the participant's note block has been locked by an administrator (see locked).
Name
locked
Type
boolean
Description
Whether an administrator has locked this participant's note block. When true, content is null.
Name
hasForm
Type
boolean
Description
Whether a form submission is attached to this contribution. The form's field values are not exposed.
Name
attachments
Type
integer
Description
The number of files attached to this contribution.
Name
livemode
Type
boolean
Description
true when the item was returned for a live (ds_live_…) key, false in test mode.

GET/v1/shift-notes

List shift notes

Returns a paginated list of shift note items, ordered by timestamp (most recent first). Requires the read:notes scope. Filter to a single participant and/or a date window with the optional attributes below.

Optional attributes

Name
participantId
Type
integer
Description
Only include notes about this participant.
Name
from
Type
string
Description
Only include notes at or after this ISO 8601 datetime (UTC).
Name
to
Type
string
Description
Only include notes before this ISO 8601 datetime (UTC).
Name
limit
Type
integer
Description
The maximum number of items to return, 1–100. Defaults to 25.
Name
starting_after
Type
integer
Description
A cursor for pagination — the id of the last shift note from the previous page. Returns the items immediately after it.

Request

GET

/v1/shift-notes

curl -G https://api.diversitysync.com/v1/shift-notes \
  -H "Authorization: Bearer {access_token}" \
  -d participantId=1043 \
  -d limit=25

Response

{
  "object": "list",
  "url": "/v1/shift-notes",
  "has_more": true,
  "data": [
    {
      "object": "shift_note",
      "id": 55218,
      "ref": "a1c2e3f4…",
      "timestamp": "2026-06-02T14:32:00Z",
      "participant": { "id": 1043, "name": "Riley Chen" },
      "staff": { "id": 482, "name": "Jordan Avery" },
      "shiftId": 90213,
      "content": "Attended hydrotherapy. Settled and engaged well.",
      "locked": false,
      "hasForm": false,
      "attachments": 1,
      "livemode": true
    }
  ]
}