Trainee forms

Coaches send forms to trainees: intake questionnaires, recurring check-ins and one-time forms. Each send is a FormAssignment. The trainee app lists the pending ones, renders the form from its schema and submits the answers. Mount: /v1/trainee/forms, router traineeFormsRouter in src/modules/forms/forms.routes.ts. The service is built by createWiredFormsService in forms.wiring.ts, which attaches every submit side effect. Lane: trainee. The router mounts authenticateTrainee only. It does not use the app access guard. Instead the forms service applies its own rule: while Client.planFrozenOn is set, the list is empty and the other two endpoints return 403. Preview tokens can read forms and cannot submit. See Authentication. Documents to sign (form type PDF_SIGNATURE) are never served here. They are signed on a public web page. See Public endpoints.

Endpoints

`GET /v1/trainee/forms`

Lists the forms waiting for the trainee. Auth: trainee token. No parameters. An assignment is listed when all of these hold:

it belongs to the trainee and the token’s studio,
its status is PENDING,
it has no dueAt, or dueAt is now or earlier,
its template is not a document to sign.

Results are ordered by creation time, newest first. A trainee whose plan is frozen gets an empty list. Response: 200.

{
  "ok": true,
  "data": {
    "items": [
      {
        "id": "cm3a1s4de000vl908e9z2f6aw",
        "status": "PENDING",
        "dueAt": "2026-10-07T05:00:00.000Z",
        "prompt": "Please fill this before our call",
        "formVersion": 3,
        "template": {
          "id": "cm1f3a2bc0005",
          "name": "Weekly check-in",
          "type": "CHECK_IN",
          "description": null
        }
      }
    ]
  },
  "requestId": "01JB2M8Q4T6W9XK3C5V7N0PZRD"
}

string

The assignment id. This is the :id used by the two endpoints below, not the template id.

string | null

A short note the coach attached when sending.

string

The form’s display name for trainees (schema.settings.displayName) when set, else the coach-facing name.

string

INTAKE, CHECK_IN or ONE_TIME.

Errors: none beyond the lane errors.

`GET /v1/trainee/forms/:id`

Returns one assignment with the full form schema to render. Auth: trainee token.

string

required

The assignment id.

The schema is the template’s current schema passed through normalizeFormSchema, which upgrades older stored shapes to version 2. Completed assignments can also be loaded. Check status before offering a submit. Response: 200.

{
  "ok": true,
  "data": {
    "id": "cm3a1s4de000vl908e9z2f6aw",
    "status": "PENDING",
    "formVersion": 3,
    "template": {
      "id": "cm1f3a2bc0005",
      "name": "Weekly check-in",
      "type": "CHECK_IN",
      "description": null
    },
    "schema": {
      "schemaVersion": 2,
      "fields": [
        {
          "id": "f1",
          "type": "weight",
          "key": "weight",
          "label": "Current weight",
          "required": true,
          "order": 0,
          "page": 0,
          "saveToClient": true,
          "validation": { "min": 30, "max": 250, "unit": "kg" }
        },
        {
          "id": "f2",
          "type": "rating",
          "key": "energy",
          "label": "Energy this week",
          "required": false,
          "order": 1,
          "page": 0,
          "config": { "stars": 5 }
        },
        {
          "id": "f3",
          "type": "text",
          "key": "energy_note",
          "label": "What got in the way?",
          "required": true,
          "order": 2,
          "page": 0,
          "condition": { "enabled": true, "sourceFieldId": "f2", "operator": "lt", "value": 3 }
        }
      ],
      "settings": {
        "rtl": true,
        "submitLabel": "Send",
        "pages": [{ "id": "p1", "title": "This week" }]
      }
    }
  },
  "requestId": "01JB2M8Q4T6W9XK3C5V7N0PZRD"
}

Schema reference

FormSchemaV2 is defined in src/modules/forms/form-schema.ts.

Field key	Type	Notes
`id`	string	Stable field id. Conditions reference it as `sourceFieldId`
`type`	string	One of the field types below
`key`	string	The key the answer is sent under
`label`, `placeholder`, `helpText`	string	Display text
`required`	boolean
`order`, `page`	number	Position. `page` is the index into `settings.pages`
`saveToClient`	boolean	When `true`, the answer is copied onto the trainee’s profile or tracking data on submit
`validation`	object	`min`, `max`, `minLength`, `maxLength`, `pattern`, `multiline`, `unit`
`options`	array	`{ value, label }` for `dropdown` and `goal`
`config`	object	`multiple` (dropdown), `stars`, `minLabel`, `maxLabel` (rating), `pose` (image upload), `measurement` (body measurement), `hiddenCategoryIds` (food preferences), `accept`, `maxSizeMb`
`content`	object	Text and media for display-only blocks
`link`	object	`{ label, url }` on a confirmation checkbox
`condition`	object	`{ enabled, sourceFieldId, operator, value, value2 }`
`visibleIf`	object	Legacy single-field rule `{ fieldKey, equals }`. Still honoured

Field types (FORM_FIELD_TYPES):

Group	Types
Text and numbers	`text`, `number`, `range`, `rating`
Profile	`phone`, `email`, `israeli_id`, `age`, `height`, `weight`, `body_measurement`, `goal`, `gender`, `date`, `birth_date`
Choice	`dropdown`, `checkbox_confirmation`, `food_preferences`
Uploads	`image_upload`, `video_upload`, `signature`
Display only, never answered	`read_more`, `coach_message`, `text_block`, `media_block`

settings holds rtl, pages (each with id, optional title, ctaLabel and its own condition), and optional submitLabel, successMessage, displayName and thankYou.

Conditions

A field or a page can be shown only when another field’s answer matches. Operators by source kind (form-conditions.ts):

Source kind	Operators
Numeric	`eq`, `ne`, `gt`, `lt`, `empty`, `filled`
Date	`on`, `after`, `before`, `between`, `age_gt`, `age_lt`, `age_eq`, `empty`, `filled`
Choice	`eq`, `ne`, `empty`, `filled`
Boolean	`checked`, `unchecked`
Presence	`empty`, `filled`

The engine fails open: a condition that is disabled, points at a missing field or cannot be evaluated leaves the field visible. The same engine is mirrored in the web builder and the mobile app, so all three agree on what is visible. The server evaluates it again on submit and never trusts the client’s view. Errors:

Code	Status	When
`FORBIDDEN`	403	`forms are unavailable while the plan is frozen`
`NOT_FOUND`	404	`form assignment not found`: wrong id, another trainee’s or studio’s assignment, or a document to sign

`POST /v1/trainee/forms/:id`

Submits the trainee’s answers and completes the assignment. Auth: trainee token. Refused for preview tokens.

string

required

The assignment id.

object

required

A map of field key to answer. Unknown keys and answers to hidden fields are dropped.

Answer formats by field type:

Type	Answer	Server check
`text`	string	`minLength`, `maxLength` when set
`number`, `range`, `age`, `height`, `weight`, `body_measurement`	number or numeric string, decimals allowed	Must be numeric, then `min` and `max` when set
`rating`	integer	From 1 to `config.stars` (default 5)
`email`	string	Email pattern
`phone`	string	Must normalize to a valid phone
`israeli_id`	string	Checksum validated
`gender`	`male` or `female`
`date`, `birth_date`	string	Must parse as a date
`dropdown`, `goal`	an option `value`, or an array of values when `config.multiple` is `true`	Every value must be one of the options
`checkbox_confirmation`	boolean	A required one must be exactly `true`
`image_upload`, `video_upload`	URL string from Trainee uploads	Must be a string
`signature`	media URL string	Must be a normalized media URL
`food_preferences`	`{ excludedCategoryIds, excludedFoodIds, includedExceptionIds }`	Never rejected. Any shape is normalized, and “nothing excluded” is a valid answer

A required field with an empty answer (undefined, null, empty string or empty array) is an error. Fields hidden by a condition are skipped entirely, so a required but hidden field never blocks the submit. What the service does on a valid submit:

Strips answers of hidden and display-only fields (stripHiddenAnswers).
Creates a FormResponse with the answers, the assignment’s formVersion, a schemaSnapshot of the schema as answered, and submittedAt.
Marks the assignment COMPLETED with completedAt.
For an INTAKE form, tells the subscription starter that the intake form is done. A subscription that was waiting for it starts now.
Copies saveToClient answers onto the trainee, best effort (applyClientCardSaves):
- email, phone, israeli_id, age, height, birth_date (which also recomputes age), goal and weight update the Client profile.
- Each weight answer also creates a WeightEntry with source: "form" and the response id.
- body_measurement answers are merged into today’s DailyMetric.measurements under the field’s config.measurement key (chest, waist, hips, arm or thigh).
- image_upload answers that look like image URLs create a ClientPhoto with source: "form", the response id and the field’s config.pose. A failure in this step never fails the submission.
Fires the submitted hook (formSubmittedHandler), also best effort:
- FORM_FILLED webhooks registered through the Automation API are queued for delivery.
- A FORM_FILLED automation flow runs when the studio has one. Otherwise the legacy “form filled” task is created for the coach.
- The same pair for low ratings: the rating-below flow, or the legacy rating task.

The AI summary of a response is generated later, when a coach opens it on the web. It is not part of the submit. Response: 201. The created FormResponse row.

{
  "ok": true,
  "data": {
    "id": "cm3b3u6ef000xl908g1b4h8cy",
    "formTemplateId": "cm1f3a2bc0005",
    "assignmentId": "cm3a1s4de000vl908e9z2f6aw",
    "clientId": "cm2k9x1ab0001l508u3f7q2wd",
    "formVersion": 3,
    "answers": { "weight": 71.4, "energy": 4 },
    "schemaSnapshot": { "schemaVersion": 2, "fields": [], "settings": { "rtl": true, "pages": [] } },
    "handledNote": null,
    "handledById": null,
    "handledByName": null,
    "handledAt": null,
    "documentUrl": null,
    "signingAudit": null,
    "submittedAt": "2026-10-07T07:15:00.000Z",
    "createdAt": "2026-10-07T07:15:00.000Z"
  },
  "requestId": "01JB2M8Q4T6W9XK3C5V7N0PZRD"
}

schemaSnapshot is the full schema and is shortened here. The row may carry further columns of the FormResponse model. Errors:

Code	Status	When
`VALIDATION`	422	The body has no `answers` object
`BAD_REQUEST`	400	An answer failed validation. See below
`FORBIDDEN`	403	`forms are unavailable while the plan is frozen`
`NOT_FOUND`	404	`form assignment not found`
`CONFLICT`	409	`form already submitted`

Answer errors are not Zod errors. The message is the first error in Hebrew followed by the field label in quotes, clipped to 60 characters, and details lists every failed field:

{
  "ok": false,
  "code": "BAD_REQUEST",
  "message": "שדה חובה: \"Current weight\"",
  "details": [
    { "key": "weight", "label": "Current weight", "message": "שדה חובה" },
    { "key": "energy", "label": "Energy this week", "message": "דירוג לא תקין" }
  ],
  "requestId": "01JB2M8Q4T6W9XK3C5V7N0PZRD"
}

The app uses details[].key to outline the fields that need attention.

Notifications for pending forms

The trainee lane has no endpoint for “new form” events. Announcements are pushed:

A coach-assigned form pushes the FORM_SENT notification right away when the trainee has a device registered.
notifyPendingForms announces forms that became visible later (a dueAt that has now passed) and runs again whenever the app registers a push token. See POST /v1/trainee/push-token on Profile and home.

The app should refetch GET /v1/trainee/forms when it opens and when it receives a form notification.

API basics

Trainees

Plans and libraries

Tracking

Imports

Forms

Tasks and automation

Communication

Studio and billing

Admin and internal services

Trainee app API

Partner and automation

Public, internal and auth

Endpoints

`GET /v1/trainee/forms`

`GET /v1/trainee/forms/:id`

Schema reference

Conditions

`POST /v1/trainee/forms/:id`

Notifications for pending forms

​Endpoints

​GET /v1/trainee/forms

​GET /v1/trainee/forms/:id

​Schema reference

​Conditions

​POST /v1/trainee/forms/:id

​Notifications for pending forms

Endpoints

`GET /v1/trainee/forms`

`GET /v1/trainee/forms/:id`

Schema reference

Conditions

`POST /v1/trainee/forms/:id`

Notifications for pending forms