Client Notes

Client notes can contain private coaching context. Grant note scopes only to trusted server-to-server integrations.

List notes

GET /public/v1/clients/{clientId}/notes
Authorization: Bearer <access_token>

Required scope:

client_notes:read

Query parameters:

Parameter	Type	Notes
`limit`	integer	Cursor page size
`cursor`	string	Cursor returned by the previous response
`filter`	string	`all`, `notes`, `pinned`, or `shared`

The response returns sanitized note objects. Internal sort fields, coach avatar URLs, and attachment media URLs are not included. Output fields:

Field	Type	Nullable	Description
`data.notes[].noteId`	string	no	Note ID.
`data.notes[].title`	string	no	Note title.
`data.notes[].notes`	string	no	Full note text.
`data.notes[].date`	string	yes	Note date.
`data.notes[].editedAt`	string	yes	Last edit timestamp.
`data.notes[].pinned`	boolean	no	Pinned flag.
`data.notes[].visibleToClient`	boolean	no	Client visibility flag.
`data.notes[].tags[]`	string[]	no	Note tags.
`data.notes[].mentions[].id`	string	no	Mention ID when available.
`data.notes[].mentions[].name`	string	no	Mention display name.
`data.notes[].attachments[].documentId`	string	yes	Linked document ID.
`data.notes[].attachments[].name`	string	no	Attachment name.
`data.notes[].attachments[].size`	number	no	Attachment size.
`data.notes[].attachments[].type`	string	no	Attachment MIME/type string.
`data.notes[].coach.coachId`	string	yes	Coach ID.
`data.notes[].coach.name`	string	no	Coach display name.
`data.pagination.filter`	string	no	Applied filter: `all`, `notes`, `pinned`, or `shared`.
`data.pagination.limit`	integer	no	Cursor page size after normalization.
`data.pagination.returnedItems`	integer	no	Number of items returned in this page.
`data.pagination.totalItems`	integer	no	Total items for the applied filter.
`data.pagination.nextCursor`	string	yes	Cursor for the next page when available.
`data.pagination.hasMore`	boolean	no	Whether another cursor page exists.
`data.counts.all`	integer	no	Total notes including pinned and shared notes.
`data.counts.notes`	integer	no	Non-pinned notes count.
`data.counts.pinned`	integer	no	Pinned notes count.
`data.counts.shared`	integer	no	Client-visible notes count.

Create a note

POST /public/v1/clients/{clientId}/notes
Authorization: Bearer <access_token>
Content-Type: application/json

Required scope:

client_notes:write

{
  "title": "Check-in",
  "notes": "Follow up next week.",
  "visibleToClient": false,
  "pinned": false,
  "tags": ["follow-up"]
}

Request body fields:

Field	Type	Required	Rule
`title`	string	conditional	Trimmed string. A create request must contain at least one of `title`, `notes`, non-empty `tags[]`, or non-empty `attachments[]`.
`notes`	string	conditional	Trimmed string. A create request must contain at least one content field.
`visibleToClient`	boolean	no	Preferred public field for client visibility.
`visibileToClient`	boolean	no	Legacy misspelled alias accepted for backwards compatibility.
`pinned`	boolean	no	Pinned flag.
`tags[]`	string[]	no	Tags are trimmed, leading `#` is removed, empty tags are ignored, and duplicates are removed.
`mentions[]`	string[] or object[]	no	Strings become `{ name }`; objects may use `id`/`_id` and `name`/`label`. Empty mentions are ignored.
`attachments[].documentId`	string	yes	Optional linked document ID. Must be a valid ObjectId when supplied.
`attachments[].name`	string	no	Required for an attachment entry to be kept. Empty attachment entries are ignored.
`attachments[].size`	number	no	Rounded positive number; invalid or missing values become `0`.
`attachments[].type`	string	no	Attachment MIME/type string.

Validation:

Rule	Behavior
Client access	`clientId` must belong to the authenticated company. The request never accepts `companyId`.
Coach context	The OAuth client must have a usable default coach context for attribution.
Content	Create requires at least one content field: title, notes, tags, or attachments. Mentions alone are not enough.
Field types	Non-string `title`/`notes`, non-boolean visibility/pinned values, non-array tags/mentions/attachments, and invalid attachment document IDs are rejected.
Media URLs	Attachment media values may be stored internally but are never returned by the Public API note DTO.

Response fields:

Field	Type	Nullable	Description
`data.note.noteId`	string	no	Note ID.
`data.note.title`	string	no	Note title.
`data.note.notes`	string	no	Full note text.
`data.note.date`	string	yes	Note date.
`data.note.editedAt`	string	yes	Last edit timestamp.
`data.note.pinned`	boolean	no	Pinned flag.
`data.note.visibleToClient`	boolean	no	Client visibility flag.
`data.note.tags[]`	string[]	no	Note tags.
`data.note.mentions[].id`	string	no	Mention ID when available.
`data.note.mentions[].name`	string	no	Mention display name.
`data.note.attachments[].documentId`	string	yes	Linked document ID.
`data.note.attachments[].name`	string	no	Attachment name.
`data.note.attachments[].size`	number	no	Attachment size.
`data.note.attachments[].type`	string	no	Attachment MIME/type string.
`data.note.coach.coachId`	string	yes	Coach ID.
`data.note.coach.name`	string	no	Coach display name.

Update a note

PATCH /public/v1/clients/{clientId}/notes/{noteId}
Authorization: Bearer <access_token>
Content-Type: application/json

Required scope:

client_notes:write

{
  "pinned": true
}

Update accepts title, notes, visibleToClient, legacy visibileToClient, pinned, tags[], mentions[], and attachments[] with the validation rules described for create. Update requests are partial, but at least one recognized mutable field must be supplied. The resulting note must still contain content through title, notes, tags, or attachments; an update that would leave the note empty is rejected. Response fields:

Field	Type	Nullable	Description
`data.note.noteId`	string	no	Note ID.
`data.note.title`	string	no	Note title.
`data.note.notes`	string	no	Full note text.
`data.note.date`	string	yes	Note date.
`data.note.editedAt`	string	yes	Last edit timestamp.
`data.note.pinned`	boolean	no	Pinned flag.
`data.note.visibleToClient`	boolean	no	Client visibility flag.
`data.note.tags[]`	string[]	no	Note tags.
`data.note.mentions[].id`	string	no	Mention ID when available.
`data.note.mentions[].name`	string	no	Mention display name.
`data.note.attachments[].documentId`	string	yes	Linked document ID.
`data.note.attachments[].name`	string	no	Attachment name.
`data.note.attachments[].size`	number	no	Attachment size.
`data.note.attachments[].type`	string	no	Attachment MIME/type string.
`data.note.coach.coachId`	string	yes	Coach ID.
`data.note.coach.name`	string	no	Coach display name.

Delete a note

DELETE /public/v1/clients/{clientId}/notes/{noteId}
Authorization: Bearer <access_token>

Required scope:

client_notes:write

Deleting a note follows the existing FITsociety note behavior: the embedded note is removed and the operation is irreversible.

The delete endpoint returns the standard success envelope with no data payload. Invalid client or note IDs return client errors; inaccessible notes return not found.

Start here

Public API guides

Access Devices

List notes

Create a note

Update a note

Delete a note

​List notes

​Create a note

​Update a note

​Delete a note

List notes

Create a note

Update a note

Delete a note