Clients API - Perform

The clients module owns the trainee record (Client in Prisma). It lists and filters trainees, creates and edits them, keeps the coach assignments, stores each staff member’s saved filters, and serves the trainee board that the coach web app opens for one trainee. Source: backend/apps/core-api/src/modules/clients/.

Mounting and auth

clientsRouter is mounted twice in modules/index.ts. Both mounts run the same router, so every path below exists under both prefixes.

Prefix	Lane	Middleware in front of the router
`/v1/web/clients`	Web gateway	`requireServiceAuth` (HMAC), `webUserContext`, `webLimiter`
`/v1/clients`	Bearer	`replayProtection`, then `authenticate(sessionVerifier)`

The headings on this page use the web prefix. Replace /v1/web/clients with /v1/clients for the bearer lane. Both lanes set req.auth to { userId, studioId, role }. On the web lane the values come from the x-studio-id, x-user-id and x-user-role headers. An unknown or missing x-user-role is read as SUB_COACH. See API overview for the lanes and the response envelope.

Roles

The routes file uses no requireRole guard. Any authenticated caller of either lane reaches every route. What a caller can see is narrowed by coach access instead.

Coach access scoping

router.use(withCoachAccess(ctx.prisma)) runs first. It loads the caller’s Coach row by studioId and externalUserId and resolves a CoachAccess value (middleware/coach-access.ts):

Role OWNER: unrestricted.
A Coach row with active: false: the request fails with FORBIDDEN (“this team member has been removed”).
No Coach row: unrestricted. This keeps callers who predate the permission model working.
A HEAD_COACH row, or a SUB_COACH row with no stored permissions blob: unrestricted.
A SUB_COACH row whose permissions.trainees is assigned: restricted to trainees that have a ClientCoach row for this coach.

The controller turns this into a scope, { assignedCoachId }, which is null for unrestricted callers. The scope never comes from the request. router.use('/:id', requireAssignedClient(ctx.prisma)) guards every route that addresses one trainee, including the mounted tracking and subscriptions routers. A restricted coach who asks for a trainee they are not assigned to gets NOT_FOUND (“client not found”), the same answer as for a trainee of another studio.

Mounted sub-routers

Two routers hang off this one and are documented on their own pages:

/:id/tracking mounts clientTrackingRouter. See Client tracking.
/:clientId/subscriptions mounts clientSubscriptionsRouter. See Client subscriptions.

The client object

Most endpoints return the client shaped by shapeClient in clients.repository.ts. It is every scalar column of the Client model plus three derived fields:

coaches: array of { id, name } from the ClientCoach join rows, oldest assignment first, with the primary coach (coachId) moved to the front.
coverageEndsOn: the latest endsOn across the client’s own endsOn and its SCHEDULED, ACTIVE and FROZEN subscriptions. This is the date to show as “covered until”.
awaitingStart: the startTrigger of the client’s AWAITING_START subscription (INTAKE_FORM, FIRST_PLAN or FIRST_WORKOUT), or null.

{
  "id": "cmf2k1x9a0001abcd1234efgh",
  "studioId": "cmf1aa0000000studio000001",
  "coachId": "cmf1bb0000000coach0000001",
  "productId": "cmf1cc0000000product00001",
  "externalUserId": null,
  "name": "Dana Levi",
  "firstName": "Dana",
  "lastName": "Levi",
  "email": "dana@example.com",
  "phone": "0501234567",
  "status": "ACTIVE",
  "goal": "Lose 5 kg",
  "planName": "3 month coaching",
  "priceAgorot": 120000,
  "tags": ["morning", "vip"],
  "birthDate": "1994-03-12T00:00:00.000Z",
  "age": 32,
  "israeliId": null,
  "avatarUrl": null,
  "gender": "FEMALE",
  "heightCm": 168,
  "weightKg": 67.5,
  "tdee": 2100,
  "bmrMethod": null,
  "activityFactor": 1.4,
  "waterGoalMl": 2500,
  "stepsGoal": 8000,
  "goalWeightKg": 62,
  "startedOn": "2026-09-01T00:00:00.000Z",
  "endsOn": "2026-12-01T00:00:00.000Z",
  "planFrozenOn": null,
  "planRemainingDays": null,
  "appAccessWhileFrozen": false,
  "lastCheckInAt": "2026-10-05T07:41:10.000Z",
  "lastCheckInPlatform": "ios",
  "timezone": "Asia/Jerusalem",
  "onboardingFormId": "cmf1dd0000000form00000001",
  "updateFormId": "cmf1dd0000000form00000002",
  "updateCadence": "WEEKLY",
  "updateWeekday": 0,
  "updateDayOfMonth": null,
  "updateAnchorOn": null,
  "updateNextOn": null,
  "updateSkipOn": null,
  "lastUpdateFormSentAt": null,
  "lastCheckInReminderAt": null,
  "foodPreferences": null,
  "foodPreferencesUpdatedAt": null,
  "mutedNotificationGroups": [],
  "deletedAt": null,
  "createdAt": "2026-09-01T08:15:00.000Z",
  "updatedAt": "2026-10-05T07:41:10.000Z",
  "coaches": [{ "id": "cmf1bb0000000coach0000001", "name": "Noa Cohen" }],
  "coverageEndsOn": "2026-12-01T00:00:00.000Z",
  "awaitingStart": null
}

productId, planName, priceAgorot, startedOn, endsOn, planFrozenOn, planRemainingDays and status on the client are a mirror of its primary subscription. syncMirror in the client-subscriptions service rewrites them after every subscription change. ClientSubscription is the source of truth.

List and filters

`GET /v1/web/clients`

Returns one page of the studio’s trainees, newest first (createdAt descending), with the filtered total and three status bucket counts. Auth: web lane or bearer lane, any role. A restricted coach only sees assigned trainees.

string

Exact match on the stored Client.status. One of ACTIVE, PAUSED, CHURN_RISK, CHURNED, ARCHIVED.

string

Only trainees with a ClientCoach assignment to this coach id.

string

Free text. Trimmed, then matched as described under “Search” below.

string

A JSON-encoded array of filter rules. See “Filter rules” below. A value that is not valid JSON, or does not match the rule schema, is ignored and filters nothing.

string

One of active, inactive, inactiveWithAccess. See “Lifecycle” below.

string

One of onTrack, undocumented. See “Derived filters” below.

string

One of start, middle, ending, ended, expired. See “Derived filters” below.

string

One of today, week, none. See “Derived filters” below.

number

default:"1"

Positive integer.

number

default:"20"

Positive integer, maximum 500.

All filters are combined with AND. The restricted-coach condition is appended last, so neither coachId nor a rule can widen it. Response: data holds items (client objects), total (rows matching the filters), statusCounts, page and pageSize. statusCounts splits the filtered set into active, inactive and inactiveWithAccess using the lifecycle conditions. active is computed as total minus the other two.

{
  "ok": true,
  "data": {
    "items": [
      {
        "id": "cmf2k1x9a0001abcd1234efgh",
        "name": "Dana Levi",
        "status": "ACTIVE",
        "coaches": [{ "id": "cmf1bb0000000coach0000001", "name": "Noa Cohen" }],
        "coverageEndsOn": "2026-12-01T00:00:00.000Z",
        "awaitingStart": null
      }
    ],
    "total": 42,
    "statusCounts": { "active": 35, "inactive": 5, "inactiveWithAccess": 2 },
    "page": 1,
    "pageSize": 20
  },
  "requestId": "req_01"
}

The item above is shortened. Each item is the full client object. Errors: VALIDATION for a query that fails the Zod schema (for example pageSize over 500). UNAUTHORIZED when req.auth is missing. FORBIDDEN when the caller is a dismissed team member.

Search

searchConditions builds an OR of:

name contains the term, case insensitive.
email contains the term, case insensitive.
israeliId contains the term.
id equals the term.
phone contains the term. When the term has three or more digits, the digits are extracted, a leading 972 or 234 country code and leading zeros are stripped, and the phone is matched against each of: the raw digits, the core number, the core with a leading 0, and the core with 972 or 234 in front.

Lifecycle

traineeStatusConditions derives these from the plan fields on the client, not from Client.status:

Value	Condition
`active`	`planFrozenOn` is null and `endsOn` is null or not yet passed
`inactive`	`endsOn` has passed or `planFrozenOn` is set, and `appAccessWhileFrozen` is false
`inactiveWithAccess`	`endsOn` has passed or `planFrozenOn` is set, and `appAccessWhileFrozen` is true

A trainee with no endsOn and no freeze counts as active.

Derived filters

Defined in clients.derived-filters.ts. “Coverage end” means the latest end date across Client.endsOn and the live (SCHEDULED, ACTIVE, FROZEN) subscriptions.

Parameter	Value	Condition
`health`	`onTrack`	`lastCheckInAt` within the last 7 days
`health`	`undocumented`	`lastCheckInAt` is null or older than 7 days
`activity`	`today`	`lastCheckInAt` within the last 24 hours
`activity`	`week`	`lastCheckInAt` between 7 days ago and 24 hours ago
`activity`	`none`	`lastCheckInAt` is null or older than 7 days
`stage`	`expired`	coverage ended more than 1 day ago
`stage`	`ended`	not expired, and `status` is `CHURNED` or `ARCHIVED`
`stage`	`ending`	`status` is not `CHURNED` or `ARCHIVED`, and coverage ends within the next 21 days
`stage`	`start`	not expired, not ended, not ending, and `startedOn` is null or within the last 30 days
`stage`	`middle`	not expired, not ended, not ending, and `startedOn` is 30 or more days ago

Filter rules

rules is a JSON array. Each rule matches the filterRule schema in clients.schema.ts:

Field	Type	Notes
`field`	string, required	One of `status`, `coach`, `age`, `formSubmitted`, `lastActivity`, `platform`, `nutritionPlan`, `workoutPlan`, `subscriptionPlan`, `subscriptionStart`, `subscriptionEnd`, `gender`, `tags`, `weight`, `goalWeight`, `joinDate`, `daysToEnd`, `frozen`
`operator`	string, required	Meaning depends on `field`
`value`	string	Single value
`values`	string array	Multi value
`min`, `max`	string	Range bounds (numbers or `YYYY-MM-DD` dates, depending on the field)
`n`	string	A count or a window length
`unit`	string	`days`, `weeks` or `months`. A month counts as 30 days

Rules are ANDed. A rule that is incomplete (for example an empty values array or a blank number) produces no condition and filters nothing.

status

value is active, inactive or inactiveWithAccess and defaults to active. The retired values churned and frozen are read as inactive. The condition is the same lifecycle condition as the lifecycle query parameter. Operator isNot negates it.

coach

values is a list of coach ids. __none__ selects trainees with no coach assignment and can be mixed with real ids (OR). Operator notOneOf negates the condition.

age

Computed from birthDate at query time. Operators gt and lt read value and are strict: older than 40 starts at 41. Any other operator reads min and max as an inclusive range, and either bound alone is accepted. A trainee with no birth date never matches.

formSubmitted and lastActivity

Both read n and unit as a look-back window. formSubmitted matches a trainee with a FormResponse created inside the window. lastActivity matches lastCheckInAt inside the window. Operator notWithin negates the condition, which also matches trainees with no data at all.

platform

values holds ios, android or __none__. A platform matches when lastCheckInPlatform equals it, or when lastCheckInPlatform is unknown and the trainee has a push token for that platform. __none__ matches trainees with no known check-in platform and no iOS or Android push token. Operator notOneOf negates.

nutritionPlan, workoutPlan, subscriptionPlan

Defined in clients.plan-filters.ts.

nutritionPlan looks at the trainee’s programs with status ACTIVE or PAUSED and type NUTRITION or COMBINED.
workoutPlan looks at programs with status ACTIVE or PAUSED and type TRAINING or COMBINED.
subscriptionPlan looks at subscriptions with status SCHEDULED, ACTIVE or FROZEN.

Operators:

planOneOf and planNotOneOf read values. For programs the ids are matched against sourceTemplateId. For subscriptions they are matched against productId. __none__ selects trainees with no such plan.
planCountIs, planCountAtLeast and planCountAtMost read n as a non-negative integer. Counts of 0 and 1 fold into the main query. Other counts run a groupBy over the plan rows first, narrowed by the rest of the request, and feed the matching ids back into the list query.

subscriptionStart and subscriptionEnd

min and max are YYYY-MM-DD dates read as whole UTC days. One bound alone reads as “from” or “until”. subscriptionStart compares Client.startedOn. subscriptionEnd compares the coverage end: the lower bound matches when the client endsOn or any live subscription reaches it, and the upper bound matches only when no live subscription runs past it. A trainee with no end date at all never matches an upper bound.

gender

value is MALE, FEMALE or __none__ (no gender set). Operator isNot negates.

`GET /v1/web/clients/selection`

Returns the id and name of every trainee matching the same filters as the list, with no paging. The trainee board uses it for “select all” across the whole filtered set. Auth: web lane or bearer lane, any role. Restricted coaches only get assigned trainees. The query is parsed with the same clientListQuery schema as the list, so it accepts status, coachId, search, rules, lifecycle, health, stage and activity. page and pageSize are parsed but not used. Response:

{
  "ok": true,
  "data": {
    "items": [
      { "id": "cmf2k1x9a0001abcd1234efgh", "name": "Dana Levi", "firstName": "Dana" }
    ],
    "total": 1
  }
}

Errors: VALIDATION, UNAUTHORIZED, FORBIDDEN (dismissed team member).

`GET /v1/web/clients/tag-options`

Returns every distinct tag used on the studio’s trainees, sorted, for the tags filter. The query reads rows where deletedAt is null and drops blank tags. Auth: web lane or bearer lane, any role. This endpoint is not narrowed by coach scope. Response:

{ "ok": true, "data": { "tags": ["morning", "vip"] } }

Errors: UNAUTHORIZED, FORBIDDEN (dismissed team member).

Saved filters and filter state

Saved filters (SavedTraineeFilter) are named presets. They belong to one staff member (userId) inside one studio. The filter state (TraineeFilterState) is the filter bar as that staff member last left it, one row per studio and user.

`GET /v1/web/clients/saved-filters`

Lists the caller’s saved filters, favorites first, then newest first. Auth: web lane or bearer lane, any role. Response: an array.

{
  "ok": true,
  "data": [
    {
      "id": "cmf3f10000000filter000001",
      "name": "Ending this month",
      "rules": [{ "field": "daysToEnd", "operator": "lt", "value": "30" }],
      "isFavorite": true,
      "createdAt": "2026-09-20T10:00:00.000Z"
    }
  ]
}

Errors: UNAUTHORIZED, FORBIDDEN (dismissed team member).

`POST /v1/web/clients/saved-filters`

Creates a saved filter for the caller. Responds with status 201. Auth: web lane or bearer lane, any role.

string

required

Trimmed, 1 to 80 characters.

object[]

required

Array of objects. Stored as given. The rule shape is not validated here, only that each entry is an object.

Response: the created filter, same shape as a list entry (id, name, rules, isFavorite, createdAt). Errors: VALIDATION, UNAUTHORIZED.

`PATCH /v1/web/clients/saved-filters/:id`

Renames a saved filter or toggles its favorite star. Auth: web lane or bearer lane, any role. Only the caller’s own filters in the caller’s studio match.

string

required

Saved filter id.

string

Trimmed, 1 to 80 characters.

boolean

Favorite flag.

At least one of the two body fields is required. Response: the updated filter (id, name, rules, isFavorite, createdAt). Errors: NOT_FOUND (“saved filter not found”) when no filter with this id belongs to the caller. VALIDATION for an empty patch (“no fields to update”).

`DELETE /v1/web/clients/saved-filters/:id`

Deletes one of the caller’s saved filters. Auth: web lane or bearer lane, any role.

string

required

Saved filter id.

Response: { "deleted": true }. The service uses deleteMany scoped to the studio and user and does not check the count, so the response is the same when nothing matched. Errors: VALIDATION, UNAUTHORIZED.

`GET /v1/web/clients/filter-state`

Returns the caller’s remembered filter bar. When no row exists, or the stored JSON no longer matches the schema, the service returns the empty state. Auth: web lane or bearer lane, any role. Response:

{
  "ok": true,
  "data": {
    "rules": [],
    "lifecycle": "all",
    "health": null,
    "stage": null,
    "activity": null
  }
}

Errors: UNAUTHORIZED, FORBIDDEN (dismissed team member).

`PUT /v1/web/clients/filter-state`

Upserts the caller’s filter bar. Auth: web lane or bearer lane, any role.

object[]

required

Array of objects, maximum 50 entries.

string

required

One of all, active, inactive, inactiveWithAccess.

string | null

required

onTrack, undocumented or null.

string | null

required

start, middle, ending, ended, expired or null.

string | null

required

today, week, none or null.

Response: the state that was saved, same shape as the body. Errors: VALIDATION, UNAUTHORIZED.

Create and messaging

`POST /v1/web/clients`

Creates a trainee. Responds with status 201. Auth: web lane or bearer lane, any role.

string

required

At least 1 character.

string

required

At least 1 character.

string

required

At least 1 character. Stored in canonical form through normalizePhoneOrNull.

boolean

When true, sends the WhatsApp invite template after the trainee is created.

string

The subscription plan (product) to assign.

string[]

Coach ids to assign. Ids that are not coaches of this studio are dropped without an error. The first id becomes the primary coach (coachId).

string | null

Intake form to send. Must be a form of type INTAKE.

string | null

Check-in form to attach. Must be a form of type CHECK_IN.

string | null

WEEKLY, BIWEEKLY or MONTHLY.

number | null

Integer 0 to 6.

number | null

Integer 1 to 31.

string

Valid email.

string

Free text.

string

Overrides the plan name copied from the product.

number

Non-negative integer, in agorot.

string

Valid URL.

string[]

default:"[]"

Tags.

date

Coerced to a date. age is computed from it and stored.

string

MALE, FEMALE or OTHER.

number

Positive.

number

Positive.

number

Positive.

string

Free text.

number

Positive.

number

Non-negative integer.

number

Non-negative integer.

date

Subscription start. Coerced to a date.

date

Subscription end. Coerced to a date. When both dates are sent, endsOn must be on or after startedOn.

number

Positive integer. Only used when endsOn is absent.

string

DAYS or MONTHS.

What the service does, in order:

Builds name from first and last name and normalizes the phone.
When productId resolves to a product of the studio, it fills defaults from the product:
- planName from the product name, unless sent.
- startedOn is the sent value. Without one it is now, except when only a past endsOn was sent. Then the start is back-dated from endsOn by the duration.
- endsOn is the sent value, or startedOn plus durationValue and durationUnit (body first, then product). If neither the body nor the product has a duration, the request fails.
- onboardingFormId, updateFormId and priceAgorot from the product, unless the body sets them.
Validates the intake form type and the check-in form type. The check-in form’s cadence, sendWeekday and sendDayOfMonth become the defaults for updateCadence, updateWeekday and updateDayOfMonth when the body does not set them.
Resolves coachIds. A restricted coach who sends no coachIds is assigned automatically. A restricted coach must include themselves and cannot add any other coach.
Checks that the span runs forward, then inserts the client and its ClientCoach rows. When billing plan limits apply, the count and the insert run inside the studio’s trainee lock (planLimits.withTraineeRoom).
If sendWhatsappInvite is true, sends the SmartSend template trainee_invite_marketing (language he) with the first name and studio name. Failure is logged and does not fail the request. If SmartSend is not configured, a warning is logged and nothing is sent.
If the client has a productId, calls subscriptions.createInitial. This creates the first ClientSubscription row, syncs the mirror fields, fires the subscription-assigned automation hook and records a SUBSCRIPTION_PLAN / ASSIGNED activity. When neither startedOn nor endsOn was sent, the studio’s start mode can hold the subscription as AWAITING_START. See Client subscriptions.
If the result has an onboardingFormId, sends that form to the trainee through the forms service (assignForm). Failure is logged and does not fail the request.
If the result has an updateFormId, records a FORM / ASSIGNED activity. The check-in form itself is sent later by the dispatcher on its cadence.

Response: the client object. Errors:

VALIDATION: body fails the schema, including “endsOn must be on or after startedOn”.
BAD_REQUEST: the plan has no duration and none was sent. The form is the wrong type (“onboarding form must be intake”, “update form must be check-in”). The form is a document to sign (details.reason is FORM_IS_DOCUMENT_TO_SIGN). The subscription would end before it starts.
NOT_FOUND: “onboarding form not found” or “update form not found”.
FORBIDDEN: the studio’s plan is full (details.reason is PLAN_LIMIT_TRAINEES, with limit, count and planId). A restricted coach tried to assign another coach or leave themselves off.
CONFLICT: a database constraint failed (Prisma P2002 or P2003).

A productId that does not belong to the studio is not rejected by the service. The product defaults are skipped and the id is still written, so the outcome depends on the database foreign key. This path was not confirmed further.

`POST /v1/web/clients/push-message`

Sends a free-text push notification from the coach to a set of trainees. Auth: web lane or bearer lane, any role. For a restricted coach, clientIds is first narrowed to the trainees assigned to them.

string[]

required

1 to 500 trainee ids.

string

required

1 to 1000 characters. Every occurrence of the token [שם] is replaced with the trainee’s first name.

The service sends through the shared trainee notifier with notification type TRAINER_MESSAGE, so the studio’s notification settings for that type apply. Each recipient gets the message as bodyOverride with the vars trainer (studio name, or “Perform”) and name. For every trainee whose device accepted the message, it records a ClientActivity row with type MESSAGE, action SENT, entity type PUSH and the first 120 characters of the message as entityName. Trainees that were not reached get no activity row. Response:

{
  "ok": true,
  "data": { "sent": 18, "selected": 20, "unreachable": 2, "disabled": false }
}

sent: trainees reached.
selected: trainees found in the studio from the requested ids.
unreachable: selected minus sent.
disabled: true when the studio turned the TRAINER_MESSAGE type off.

When no ids are left after narrowing, the response is { "sent": 0 } only. Errors: VALIDATION. BAD_REQUEST (“push messaging is not available on this lane”) when no notifier is wired. The clients router wires one on both mounts.

Single trainee

Every route in this section runs behind requireAssignedClient.

`GET /v1/web/clients/:id`

Returns one trainee. Auth: web lane or bearer lane, any role, coach scope applied.

string

required

Client id.

Response: the client object. Errors: NOT_FOUND (“client not found”).

`PATCH /v1/web/clients/:id`

Updates a trainee. Every field is optional. Sending null clears a nullable field. Auth: web lane or bearer lane, any role, coach scope applied.

string

required

Client id.

string

At least 1 character. name is recomposed when first or last name changes.

string

At least 1 character.

string

At least 1 character. Normalized before saving.

string | null

Changes the plan. null removes it. See the plan change steps below.

string[]

Replaces the full set of assigned coaches. Unknown ids are dropped. The first id becomes the primary coach. An empty array removes all coaches.

string | null

Must be an INTAKE form.

string | null

Must be a CHECK_IN form.

string | null

WEEKLY, BIWEEKLY or MONTHLY.

number | null

Integer 0 to 6.

number | null

Integer 1 to 31.

string | null

ISO date YYYY-MM-DD. The date the biweekly cycle counts from. Stored as the start of that day in the studio timezone.

string | null

ISO date YYYY-MM-DD. A one-off date for the next check-in. Cannot be in the past (studio timezone) and cannot fall on a Saturday.

string | null

ISO date YYYY-MM-DD. A check-in date to skip.

string | null

Valid email.

string | null

Free text.

string | null

Plan name override.

number | null

Non-negative integer.

string | null

Valid URL.

string[]

Replaces the tags.

string

ACTIVE, PAUSED, CHURN_RISK, CHURNED or ARCHIVED.

date | null

age is recomputed, or cleared on null.

string | null

MALE, FEMALE or OTHER.

number | null

Positive.

number | null

Positive.

number | null

Positive, maximum 500.

number | null

Positive.

string | null

Free text.

number | null

Positive.

number | null

Non-negative integer.

number | null

Non-negative integer.

date | null

Subscription start.

date | null

Subscription end. When both dates are in the body, endsOn must be on or after startedOn.

number

Positive integer. Used to derive endsOn on a plan change.

string

DAYS or MONTHS.

boolean

Lets a frozen or ended trainee keep app access.

What the service does:

Un-archive check. Moving a trainee out of ARCHIVED calls planLimits.assertCanAddTrainees, because the trainee counts toward the plan again.
Plan change (productId differs from the stored one):
1. subscriptions.assertReplaceable refuses when the trainee has a SCHEDULED or AWAITING_START subscription.
2. planFrozenOn and planRemainingDays are cleared and appAccessWhileFrozen is set to false.
3. With productId: null, planName, endsOn and priceAgorot are cleared unless the body sets them.
4. With a new product, the same defaults as on create are applied: plan name, start date (body, then the stored one, then back-dated or now), end date from the duration, forms and price.
5. After the client row is saved, subscriptions.replaceActive cancels the ACTIVE and FROZEN subscriptions, creates a new subscription from the client’s dates when it has a product and both dates, syncs the mirror and fires the subscription-assigned hook.
6. A SUBSCRIPTION_PLAN activity is recorded with action REMOVED, EDITED or ASSIGNED.
Forms. A changed onboardingFormId or updateFormId records a FORM activity (REMOVED, EDITED or ASSIGNED). When updateFormId changes and the body sets no schedule, the cadence, weekday and day of month default to the form’s own. A cadence change with no form change records a FORM / EDITED activity.
Check-in dates (checkInDatePatch). When the cadence, weekday or day of month changes, or the check-in form is removed, and the body sets neither updateNextOn nor updateSkipOn, both are cleared. A stored updateAnchorOn that is still in the future is also cleared unless the body sets one.
Coaches. With coachIds, the ClientCoach rows are deleted and recreated in one transaction. A restricted coach must stay on the trainee, cannot add another coach and cannot remove another coach. When the set changed, syncClientCoachTasks moves the trainee’s open automated tasks (InboxItem rows with source auto) to the new coaches. A failure there is logged and does not fail the request.
Date span. When the patch touches startedOn or endsOn, the merged pair (patch plus stored row) must run forward.
Status. When status is ACTIVE, PAUSED or CHURNED, the service calls subscriptions.resync after saving. That runs reconcile and syncMirror, and syncMirror derives the status from the subscriptions again (deriveClientStatus). The stored status can therefore differ from the one sent. CHURN_RISK and ARCHIVED are kept as sent.

Response: the client object after all steps. Errors:

NOT_FOUND: “client not found”, “onboarding form not found”, “update form not found”.
VALIDATION: schema failure. “updateNextOn is in the past”. “updateNextOn cannot fall on a Saturday”. “cancel the scheduled subscription before changing the plan”, with details.conflicts.
BAD_REQUEST: the new plan has no duration and none was sent. Wrong form type. The dates would end before they start.
FORBIDDEN: plan limit on un-archive (PLAN_LIMIT_TRAINEES). Coach assignment rules (“you must stay assigned to this trainee”, “cannot assign a trainee to another coach”, “cannot unassign another coach from this trainee”).

`DELETE /v1/web/clients/:id`

Deletes the trainee. This is a hard delete (prisma.client.deleteMany). Every model that references the client cascades, so photos, logs, programs, form data, messages, subscriptions, activities and push tokens go with it. Auth: web lane or bearer lane, any role, coach scope applied.

string

required

Client id.

Response: { "deleted": true }. Errors: NOT_FOUND (“client not found”).

There is no role guard on this route and no undo. Any caller who can reach the trainee can delete them.

`POST /v1/web/clients/:id/freeze`

Freezes the trainee’s active subscription. No body. Auth: web lane or bearer lane, any role, coach scope applied.

string

required

Client id.

The service calls subscriptions.freeze. Inside one transaction it runs reconcile, finds the ACTIVE subscription, computes the remaining days (rounded up), sets the subscription to FROZEN with planFrozenOn and planRemainingDays, and syncs the mirror. The client status becomes PAUSED unless it is CHURN_RISK or ARCHIVED. Side effects: a SUBSCRIPTION_PLAN / EDITED activity row, and a SUBSCRIPTION_FROZEN push to the trainee with the studio name. Response: the client object, now with planFrozenOn and planRemainingDays set. Errors:

NOT_FOUND: “client not found”.
VALIDATION: “plan is already frozen”. “client has no active plan”. “plan has already expired”. “cancel the scheduled subscription before freezing the plan”, with details.conflicts, when a SCHEDULED or AWAITING_START subscription exists.

`POST /v1/web/clients/:id/reactivate`

Unfreezes a frozen subscription. No body. Auth: web lane or bearer lane, any role, coach scope applied.

string

required

Client id.

The service calls subscriptions.reactivate. The frozen subscription becomes ACTIVE with a new endsOn of now plus planRemainingDays. If a SCHEDULED subscription starts before that date, endsOn is cut to the scheduled start. planFrozenOn and planRemainingDays are cleared and the mirror is synced, which also resets appAccessWhileFrozen to false. Side effect: a SUBSCRIPTION_PLAN / EDITED activity row. No push is sent. Response: the client object. Errors: NOT_FOUND (“client not found”). VALIDATION (“plan is not frozen”).

`POST /v1/web/clients/:id/avatar`

Uploads a profile picture as base64 and stores its URL on the trainee. Auth: web lane or bearer lane, any role, coach scope applied.

string

required

Client id.

string

required

Base64 image data. The decoded image must be between 1 byte and 2,000,000 bytes.

string

required

image/png or image/jpeg.

The file is written to R2 at clients/<id>.png or clients/<id>.jpg, replacing any earlier file at that key. avatarUrl is saved as the public URL with a ?v=<timestamp> cache-busting suffix. Response: the client object with the new avatarUrl. Errors: NOT_FOUND. VALIDATION (“avatar image is empty”, “avatar image is too large”, or a schema failure).

`POST /v1/web/clients/:id/preview-token`

Mints a short-lived trainee token so the coach web app can load the trainee app as this trainee, in preview mode. No body. Auth: web lane or bearer lane, any role, coach scope applied.

string

required

Client id.

The token is created by createTraineeToken with the payload { clientId, studioId, preview: true }, signed with BETTER_AUTH_SECRET, and expires after PREVIEW_TTL_SECONDS (900 seconds). Response:

{ "ok": true, "data": { "token": "PREVIEW_TOKEN", "expiresInSeconds": 900 } }

Errors: NOT_FOUND.

`GET /v1/web/clients/:id/photos`

Lists the trainee’s progress photos (ClientPhoto), newest takenAt first. Auth: web lane or bearer lane, any role, coach scope applied.

string

required

Client id.

Response: an array.

{
  "ok": true,
  "data": [
    {
      "id": "cmf4p10000000photo0000001",
      "clientId": "cmf2k1x9a0001abcd1234efgh",
      "url": "https://cdn.example.com/photos/front.jpg",
      "takenAt": "2026-10-01T06:30:00.000Z",
      "source": "form",
      "pose": "FRONT",
      "formResponseId": "cmf4r10000000resp00000001",
      "createdAt": "2026-10-01T06:30:02.000Z"
    }
  ]
}

pose is FRONT, SIDE, BACK or null. The values stored in source are not defined in this module. Errors: NOT_FOUND.

`GET /v1/web/clients/:id/weights`

Lists the trainee’s weigh-ins (WeightEntry), oldest recordedAt first. Auth: web lane or bearer lane, any role, coach scope applied.

string

required

Client id.

Response: an array.

{
  "ok": true,
  "data": [
    {
      "id": "cmf4w10000000weight000001",
      "clientId": "cmf2k1x9a0001abcd1234efgh",
      "weightKg": 67.5,
      "recordedAt": "2026-10-01T06:30:00.000Z",
      "source": "form",
      "formResponseId": "cmf4r10000000resp00000001",
      "note": null,
      "createdAt": "2026-10-01T06:30:02.000Z"
    }
  ]
}

Errors: NOT_FOUND.

Board and activity

`GET /v1/web/clients/:id/board`

Returns everything the trainee card needs in one call: the client, plans, subscriptions, forms, meetings, open tasks and the activity feed. Auth: web lane or bearer lane, any role, coach scope applied.

string

required

Client id.

Response: data has these keys.

Key	Content
`client`	The client object
`programs`	Up to 500 `Program` rows of the trainee, newest first
`subscriptions`	Up to 500 `ClientSubscription` rows in every status, newest `startedOn` first
`subscriptionStartMode`	The studio setting: `ASSIGNMENT`, `INTAKE_FORM`, `FIRST_PLAN` or `FIRST_WORKOUT`
`assignments`	Up to 500 `FormAssignment` rows with `formTemplate`. `signToken`, `prefill` and `signSchema` are removed and `signingUrl` is added (a link on the coach web origin, or `null`)
`responses`	Up to 500 `FormResponse` rows with `formTemplate`, newest first
`meetings`	Up to 500 `CalendarEvent` rows, earliest `startsAt` first
`openTasks`	Up to 100 `InboxItem` rows with status `OPEN` or `SNOOZED`, with `coach` as `{ id, name }`, highest priority first
`workoutStreak`	Number of consecutive weeks, counting back from today, with at least one completed workout. Capped at 52
`lastAppPlatform`	`ios`, `android` or `null`. From `lastCheckInPlatform`, falling back to the newest push token
`activity`	The merged activity feed, newest first

The activity feed is assembled by assembleActivity from six sources, each capped at 500 rows:

Source	`type`	`id` format	`entityId`
`ClientActivity` rows	the stored type, for example `COACH_NOTE`, `MESSAGE`, `FORM`, `SUBSCRIPTION_PLAN`	the row id	the stored value
`MealLog`	`MEAL_ATE`	`meal:<id>`	meal log id
`WorkoutLog` (completed)	`WORKOUT_COMPLETED`	`workout:<id>`	the log’s `programId`
`FormResponse`	`FORM_COMPLETED`	`form:<id>`	the form template id
`TechniqueVideo`	`TECHNIQUE_VIDEO_SENT`	`video:<id>`	the video id
`InboxItem` with source `auto`	`AUTOMATION_TRIGGERED`, plus `AUTOMATION_COMPLETED` once resolved	`automation:<id>` and `automation-completed:<id>`	the inbox item id

Day boundaries use the trainee’s own timezone when set, otherwise the studio’s.

{
  "ok": true,
  "data": {
    "client": { "id": "cmf2k1x9a0001abcd1234efgh", "name": "Dana Levi" },
    "programs": [],
    "subscriptions": [],
    "subscriptionStartMode": "ASSIGNMENT",
    "assignments": [],
    "responses": [],
    "meetings": [],
    "openTasks": [],
    "workoutStreak": 4,
    "lastAppPlatform": "ios",
    "activity": [
      {
        "id": "cmf5a10000000activity0001",
        "actorId": "user_8f2c",
        "actorType": "TRAINER",
        "actorName": "Noa Cohen",
        "type": "COACH_NOTE",
        "action": null,
        "entityType": null,
        "entityId": null,
        "entityName": null,
        "metadata": { "note": "Knee feels better, back to full squats." },
        "occurredAt": "2026-10-06T09:12:00.000Z"
      },
      {
        "id": "meal:cmf5m10000000meal00000001",
        "actorType": "TRAINEE",
        "actorName": null,
        "type": "MEAL_ATE",
        "action": null,
        "entityType": "MEAL",
        "entityId": "cmf5m10000000meal00000001",
        "entityName": "Lunch",
        "metadata": { "day": "2026-10-06", "calories": 620 },
        "occurredAt": "2026-10-06T10:05:00.000Z"
      }
    ]
  }
}

client is shortened in the example. Only recorded ClientActivity entries carry actorId. Errors: NOT_FOUND.

`POST /v1/web/clients/:id/activity/notes`

Adds a free-text coach note to the trainee’s activity feed. Responds with status 201. Auth: web lane or bearer lane, any role, coach scope applied.

string

required

Client id.

string

required

Trimmed, at least 1 character. No maximum length.

The note is stored as a ClientActivity row with type COACH_NOTE, actor type TRAINER, the caller’s user id as actorId, the coach’s name as actorName (looked up from the Coach row) and the text in metadata.note. Response:

{
  "ok": true,
  "data": { "id": "cmf5a10000000activity0001", "occurredAt": "2026-10-06T09:12:00.000Z" }
}

Errors: NOT_FOUND (“client not found”). VALIDATION (empty text).

`DELETE /v1/web/clients/:id/activity/notes/:activityId`

Deletes a coach note. Only notes can be deleted, and only by their author. Auth: web lane or bearer lane, any role, coach scope applied. The caller’s user id must equal the note’s actorId.

string

required

Client id.

string

required

The ClientActivity row id.

Response: { "deleted": true }. Errors: NOT_FOUND (“note not found”) when the row does not exist for this trainee or is not a COACH_NOTE. FORBIDDEN (“only the author can delete a note”).

Food preferences

A trainee’s food preferences are the food categories and foods they do not eat. The effective value is the coach’s saved override when one exists. Otherwise it is the answer from the newest submitted form response that has a food_preferences field (the last 10 submissions of those forms are scanned).

`GET /v1/web/clients/:id/food-preferences`

Returns the effective food preferences and where they came from. Auth: web lane or bearer lane, any role, coach scope applied.

string

required

Client id.

Response:

{
  "ok": true,
  "data": {
    "value": {
      "excludedCategoryIds": ["dairy"],
      "excludedFoodIds": ["cmf6f10000000food00000001"],
      "includedExceptionIds": ["cmf6f10000000food00000002"]
    },
    "source": "form",
    "origin": {
      "formId": "cmf1dd0000000form00000001",
      "formName": "Intake questionnaire",
      "submittedAt": "2026-09-02T11:00:00.000Z"
    },
    "updatedAt": null,
    "excludedCount": 37
  }
}

source: coach, form or none.
origin: the form response the answer was read from, or null.
excludedCount: how many foods in the studio’s visible food library (global rows plus studio rows, with per-studio category overrides applied) are excluded. A food is excluded when its id is in excludedFoodIds, or when its primary category is in excludedCategoryIds and its id is not in includedExceptionIds.

Errors: NOT_FOUND (“client not found”).

`PUT /v1/web/clients/:id/food-preferences`

Saves a coach override. From then on the override wins over form answers. Auth: web lane or bearer lane, any role, coach scope applied.

string

required

Client id.

string[]

default:"[]"

Up to 5000 ids, each 1 to 128 characters.

string[]

default:"[]"

Up to 5000 ids, each 1 to 128 characters.

string[]

default:"[]"

Foods kept even though their category is excluded. Up to 5000 ids, each 1 to 128 characters.

The body is written to Client.foodPreferences and foodPreferencesUpdatedAt is set to now. Response: same shape as the GET, with source set to coach, value set to the saved body and updatedAt set to the save time. origin still names the form response, if one exists. Errors: NOT_FOUND (“client not found”). VALIDATION.

Common errors

These apply to every route on this page.

Code	Status	When
`UNAUTHORIZED`	401	Missing or invalid credentials for the lane, or missing `req.auth`
`FORBIDDEN`	403	The caller’s `Coach` row is inactive (“this team member has been removed”)
`NOT_FOUND`	404	The trainee is in another studio, or a restricted coach is not assigned to them
`VALIDATION`	422	A Zod schema rejected the path, query or body. `details` lists `path` and `message` per issue
`RATE_LIMITED`	429	Listed in the error map. The limiter itself (`webLimiter`) is configured outside this module

​Mounting and auth

​Roles

​Coach access scoping

​Mounted sub-routers

​The client object

​List and filters

​GET /v1/web/clients

​Search

​Lifecycle

​Derived filters

​Filter rules

​GET /v1/web/clients/selection

​GET /v1/web/clients/tag-options

​Saved filters and filter state

​GET /v1/web/clients/saved-filters

​POST /v1/web/clients/saved-filters

​PATCH /v1/web/clients/saved-filters/:id

​DELETE /v1/web/clients/saved-filters/:id

​GET /v1/web/clients/filter-state

​PUT /v1/web/clients/filter-state

​Create and messaging

​POST /v1/web/clients

​POST /v1/web/clients/push-message

​Single trainee

​GET /v1/web/clients/:id

​PATCH /v1/web/clients/:id

​DELETE /v1/web/clients/:id

​POST /v1/web/clients/:id/freeze

​POST /v1/web/clients/:id/reactivate

​POST /v1/web/clients/:id/avatar

​POST /v1/web/clients/:id/preview-token

​GET /v1/web/clients/:id/photos

​GET /v1/web/clients/:id/weights

​Board and activity

​GET /v1/web/clients/:id/board

​POST /v1/web/clients/:id/activity/notes

​DELETE /v1/web/clients/:id/activity/notes/:activityId

​Food preferences

​GET /v1/web/clients/:id/food-preferences

​PUT /v1/web/clients/:id/food-preferences

​Common errors

Mounting and auth

Roles

Coach access scoping

Mounted sub-routers

The client object

List and filters

`GET /v1/web/clients`

Search

Lifecycle

Derived filters

Filter rules

`GET /v1/web/clients/selection`

`GET /v1/web/clients/tag-options`

Saved filters and filter state

`GET /v1/web/clients/saved-filters`

`POST /v1/web/clients/saved-filters`

`PATCH /v1/web/clients/saved-filters/:id`

`DELETE /v1/web/clients/saved-filters/:id`

`GET /v1/web/clients/filter-state`

`PUT /v1/web/clients/filter-state`

Create and messaging

`POST /v1/web/clients`

`POST /v1/web/clients/push-message`

Single trainee

`GET /v1/web/clients/:id`

`PATCH /v1/web/clients/:id`

`DELETE /v1/web/clients/:id`

`POST /v1/web/clients/:id/freeze`

`POST /v1/web/clients/:id/reactivate`

`POST /v1/web/clients/:id/avatar`

`POST /v1/web/clients/:id/preview-token`

`GET /v1/web/clients/:id/photos`

`GET /v1/web/clients/:id/weights`

Board and activity

`GET /v1/web/clients/:id/board`

`POST /v1/web/clients/:id/activity/notes`

`DELETE /v1/web/clients/:id/activity/notes/:activityId`

Food preferences

`GET /v1/web/clients/:id/food-preferences`

`PUT /v1/web/clients/:id/food-preferences`

Common errors