> ## Documentation Index
> Fetch the complete documentation index at: https://docs.fitsociety.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Check-ups

> Schedule check-ups and read assignment status and submissions.

Use [Forms](/public-api/forms) to create and manage templates. Assignment
requires an active, non-archived template of the matching type. Archiving a
template preserves existing assignments and submitted answers.

## List assigned checkups

```http theme={null}
GET /public/v1/clients/{clientId}/checkups
Authorization: Bearer <access_token>
```

Required scope: `checkups:read`

Response fields:

| Field | Type | Nullable | Description |
| :- | :- | :- | :- |
| `data.checkups[].settingId` | string | no | Checkup setting ID. |
| `data.checkups[].formId` | string | yes | Form ID. |
| `data.checkups[].formName` | string | no | Form name. |
| `data.checkups[].scheduleType` | string | no | Schedule type. |
| `data.checkups[].lastAnswerDate` | string | yes | Last answer date. |
| `data.checkups[].nextNotificationDate` | string | yes | Next notification date. |

## Get checkup status

```http theme={null}
GET /public/v1/clients/{clientId}/checkups/{settingId}/status
Authorization: Bearer <access_token>
```

Required scope: `checkups:read`

Response fields:

| Field | Type | Nullable | Description |
| :- | :- | :- | :- |
| `data.checkup.settingId` | string | no | Checkup setting ID. |
| `data.checkup.clientId` | string | no | Client ID. |
| `data.checkup.formId` | string | no | Form ID. |
| `data.checkup.formName` | string | no | Form name. |
| `data.checkup.status` | string | no | `pending`, `submitted`, `disabled`, or `cancelled`. |
| `data.checkup.isActive` | boolean | no | Whether the assignment is active. |
| `data.checkup.scheduleType` | string | no | Schedule type only. |
| `data.checkup.lastSubmittedAt` | string | yes | Last submitted timestamp. |
| `data.checkup.nextNotificationAt` | string | yes | Next notification timestamp. |
| `data.checkup.createdAt` | string | yes | Creation timestamp. |
| `data.checkup.updatedAt` | string | yes | Last update timestamp. |

Not exposed: reminder email/chat bodies, raw schedule internals, coach IDs,
deleted flags, or draft answers.

## List checkup submissions

```http theme={null}
GET /public/v1/clients/{clientId}/checkups/submissions?dateFrom=2026-01-01&dateTo=2026-07-13
Authorization: Bearer <access_token>
```

Required scope: `checkups:read`

Query parameters:

| Parameter | Type | Required | Rule |
| :- | :- | :- | :- |
| `page` | integer | no | Minimum `1`. |
| `limit` | integer | no | Default `25`, maximum `25`. |
| `settingId` | string | no | Filter by checkup setting. |
| `dateFrom` | date/date-time | no | Must be paired with `dateTo`. |
| `dateTo` | date/date-time | no | Max 366-day range. |

Response fields:

| Field | Type | Nullable | Description |
| :- | :- | :- | :- |
| `data.page` | integer | no | Current page. |
| `data.limit` | integer | no | Page size after cap, maximum `25`. |
| `data.total` | integer | no | Total matching submissions. |
| `data.totalPages` | integer | no | Total pages. |
| `data.hasNextPage` | boolean | no | Next page availability. |
| `data.hasPrevPage` | boolean | no | Previous page availability. |
| `data.submissions[].submissionId` | string | no | Submission ID. |
| `data.submissions[].formId` | string | yes | Form ID. |
| `data.submissions[].formName` | string | no | Form name. |
| `data.submissions[].formType` | string | no | `checkup`. |
| `data.submissions[].settingId` | string | yes | Checkup setting ID when applicable. |
| `data.submissions[].submittedFor` | string | yes | Submission period/date. |
| `data.submissions[].submittedAt` | string | yes | Submission timestamp. |
| `data.submissions[].isReviewed` | boolean | no | Review status. |
| `data.submissions[].answers[].question` | string | no | Question name. |
| `data.submissions[].answers[].answerType` | string | no | Answer type. |
| `data.submissions[].answers[].answer` | string | no | Normalized answer. Media answers are `[media redacted]`. |
| `data.submissions[].answers[].answeredAt` | string | yes | Answer timestamp. |
| `data.submissions[].feedbacks[].feedback` | string | no | Feedback text. |
| `data.submissions[].feedbacks[].givenAt` | string | yes | Feedback timestamp. |

## Assign checkup

```http theme={null}
POST /public/v1/clients/{clientId}/checkups
Authorization: Bearer <access_token>
Content-Type: application/json
```

Required scope: `checkups:write`

Request body:

| Field | Type | Required | Rule |
| :- | :- | :- | :- |
| `formId` | string | yes | Existing non-deleted `checkup` form in the authenticated company. |
| `schedule.type` | string | yes | `Today`, `Daily`, `Weekly`, `Monthly`, `Weekends`, `Weekdays`, or `Custom`. |
| `schedule.weeklyOn` | string | conditional | Required for `Weekly`; weekday name. |
| `schedule.monthlyWeek` | string | conditional | Required for `Monthly`; `First`, `Second`, `Third`, `Fourth`, or `Last`. |
| `schedule.monthlyDay` | string | conditional | Required for `Monthly`; weekday name. |
| `schedule.custom.startDate` | date | conditional | Required for `Custom`. |
| `schedule.custom.repeatEvery.count` | integer | no | Must be positive when supplied. |
| `schedule.custom.repeatEvery.unit` | string | no | `day`, `week`, `month`, or `year`. |

Public API v1 does not accept reminder email/chat bodies. Reminder mutation,
feedback writes, review toggles, and schedule delete/toggle remain internal.

Response fields:

| Field | Type | Nullable | Description |
| :- | :- | :- | :- |
| `data.checkup.settingId` | string | no | Created checkup setting ID. |
| `data.checkup.formId` | string | yes | Form ID. |
| `data.checkup.formName` | string | no | Form name. |
| `data.checkup.scheduleType` | string | no | Schedule type. |
| `data.checkup.lastAnswerDate` | string | yes | Last answer date. |
| `data.checkup.nextNotificationDate` | string | yes | Next notification date. |

## Cancel checkup

```http theme={null}
POST /public/v1/clients/{clientId}/checkups/{settingId}/cancel
Authorization: Bearer <access_token>
```

Required scope: `checkups:write`

This is a soft cancel. It marks the checkup setting as deleted and clears
`nextNotificationDate`; it does not delete submitted answers.

Validation:

| Parameter | Type | Required | Rule |
| :- | :- | :- | :- |
| `clientId` | string | yes | Client must belong to the authenticated company. |
| `settingId` | string | yes | Active checkup setting for that client and company. |

Response fields:

| Field | Type | Nullable | Description |
| :- | :- | :- | :- |
| `data.checkup.settingId` | string | no | Checkup setting ID. |
| `data.checkup.clientId` | string | no | Client ID. |
| `data.checkup.formId` | string | no | Form ID. |
| `data.checkup.formName` | string | no | Form name. |
| `data.checkup.status` | string | no | `cancelled` after a successful cancel. |
| `data.checkup.isActive` | boolean | no | `false` after a successful cancel. |
| `data.checkup.scheduleType` | string | no | Schedule type only. |
| `data.checkup.lastSubmittedAt` | string | yes | Last submitted timestamp. |
| `data.checkup.nextNotificationAt` | string | yes | `null` after cancellation. |
| `data.checkup.createdAt` | string | yes | Creation timestamp. |
| `data.checkup.updatedAt` | string | yes | Last update timestamp. |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.