Partner API - Perform

The partner lane is a read-mostly API that SmartSend calls to show a trainee’s Perform data next to a WhatsApp conversation, to build campaign audiences and to act on a subscription. Its response shapes are a wire contract with SmartSend. Treat them as frozen. Mount: /v1/partner, router partnerRouter in src/modules/partner/partner.routes.ts. Lane: partner. Every route runs requirePartnerKey. The caller sends a studio API key and every query is scoped to that key’s studio.

curl 'https://perform-api.otherwise.co.il/v1/partner/ping' \
  -H 'Authorization: Bearer YOUR_API_KEY'

For Make.com and other automation tools use the Automation API. It accepts the same keys but has its own envelope, input coercion and write endpoints. Do not send automation traffic here.

Conventions on this lane

No envelope on success. Controllers call res.json(result) directly. The body is the object shown in each example.
Standard envelope on errors. Failures pass through the global error middleware: { "ok": false, "code": "...", "message": "...", "requestId": "..." }. Validation is 422 VALIDATION.
One exception. Freeze and reactivate rejections return 409 with { "error": { "code": "FREEZE_REJECTED", "message": "..." } }.
Auth errors. 401 UNAUTHORIZED with missing partner api key or invalid partner api key. See Authentication.
Rate limit. Only the global /v1 limiter: 120 requests per 60 seconds per IP by default. The module adds none.
Trainee ids. :id is always a Client.id of the key’s studio. Any other id, and a soft-deleted trainee, returns 404 trainee not found.
Dates. Instants are ISO strings. Day keys are YYYY-MM-DD in the trainee’s time zone (client zone, then studio zone, then Asia/Jerusalem).

API keys

Keys are managed from the coach web app on the web gateway lane. Mount: /v1/web/studios/current/api-keys, router studioApiKeysRouter in src/modules/partner/api-keys.routes.ts. Auth: web gateway lane (HMAC service signature plus user context), then requireRole(OWNER, HEAD_COACH). Responses use the standard envelope. How keys work (api-keys.service.ts, partner-auth.ts):

A key is pf_live_ followed by 40 hex characters from 20 random bytes.
The database stores keyHash, the SHA-256 hex of the full key, and prefix, its first 15 characters, for display. The plain key is never stored and cannot be read back.
A request is authenticated by hashing the presented key and looking the hash up. A key with revokedAt set, or whose studio is archived, is refused.
lastUsedAt is stamped at most once every 5 minutes per key, in the background.
Keys have no scopes and no expiry. Any key of a studio can call every partner and automation endpoint for that studio.

`GET /v1/web/studios/current/api-keys`

Lists the studio’s keys, newest first, including revoked ones. Auth: web gateway, role OWNER or HEAD_COACH. Response: 200.

{
  "ok": true,
  "data": {
    "keys": [
      {
        "id": "cm3e9a2hi0013l908m7h0n4ie",
        "name": "SmartSend",
        "prefix": "pf_live_3fa91c0",
        "lastUsedAt": "2026-10-07T09:12:00.000Z",
        "createdAt": "2026-09-01T10:00:00.000Z",
        "revokedAt": null
      }
    ]
  },
  "requestId": "01JB2M8Q4T6W9XK3C5V7N0PZRD"
}

Errors: 403 FORBIDDEN insufficient role.

`POST /v1/web/studios/current/api-keys`

Creates a key and returns its secret once. Auth: web gateway, role OWNER or HEAD_COACH.

string

required

A label for the key. Trimmed, 1 to 100 characters.

Response: 201. secret is the only time the full key is available.

{
  "ok": true,
  "data": {
    "key": {
      "id": "cm3e9a2hi0013l908m7h0n4ie",
      "name": "SmartSend",
      "prefix": "pf_live_3fa91c0",
      "createdAt": "2026-10-07T10:00:00.000Z"
    },
    "secret": "YOUR_API_KEY"
  },
  "requestId": "01JB2M8Q4T6W9XK3C5V7N0PZRD"
}

Errors: VALIDATION (422) for a missing or too long name. 403 insufficient role.

`POST /v1/web/studios/current/api-keys/:id/revoke`

Revokes a key. Requests with it start failing with 401 immediately. Auth: web gateway, role OWNER or HEAD_COACH.

string

required

The key id.

Revoking an already revoked key succeeds and leaves the original revokedAt. Webhooks registered with the key through the automation lane are not deleted by this call. Response: 200.

{ "ok": true, "data": { "ok": true }, "requestId": "01JB2M8Q4T6W9XK3C5V7N0PZRD" }

Errors: NOT_FOUND (404) api key not found. 403 insufficient role.

Connection

`GET /v1/partner/ping`

Checks the key and returns the studio it belongs to. Auth: studio API key. Response: 200.

{ "ok": true, "studio": { "id": "cm1s7d2kq0000jx08b4n6h1ze", "name": "Studio Fit", "slug": "studio-fit" } }

Errors: NOT_FOUND (404) studio not found.

Finding a trainee

`GET /v1/partner/trainees/by-phone/:phone`

Finds the trainee with a given phone number in the key’s studio. Auth: studio API key.

string

required

At least 6 characters. Any format.

The number is normalized with normalizePartnerPhone: digits only, a leading 972 becomes a leading 0, and a bare 9-digit number gets a leading 0. The lookup then matches on the same phone variants as trainee sign-in. Response: 200 in both cases. This endpoint never returns 404 for a miss.

{ "found": true, "clientId": "cm2k9x1ab0001l508u3f7q2wd", "name": "Noa Cohen" }

{ "found": false }

Errors: VALIDATION (422) when phone is shorter than 6 characters.

Reading a trainee

`GET /v1/partner/trainees/:id/overview`

One call for the trainee card: profile, deep links into the coach app, subscriptions, today’s nutrition and steps, training summary, check-in counters, weight change, before and after photos and the latest check-in answers. Auth: studio API key.

string

required

The trainee id.

Response: 200.

{
  "client": {
    "id": "cm2k9x1ab0001l508u3f7q2wd",
    "name": "Noa Cohen",
    "avatarUrl": null,
    "status": "ACTIVE",
    "gender": "FEMALE",
    "birthDate": "1994-03-12T00:00:00.000Z",
    "age": 32,
    "email": "noa@example.com",
    "israeliId": null,
    "heightCm": 168,
    "weightKg": 71.4,
    "goal": "Lose 5 kg",
    "coachName": "Dana Levi",
    "planName": "3 months",
    "createdAt": "2026-09-01T08:00:00.000Z",
    "lastActivityAt": "2026-10-07T07:15:00.000Z"
  },
  "links": {
    "clientCard": "https://app.byperform.co.il/studio-fit/clients/cm2k9x1ab0001l508u3f7q2wd",
    "trainingTab": "https://app.byperform.co.il/studio-fit/clients/cm2k9x1ab0001l508u3f7q2wd?tab=trainingPlans",
    "nutritionTab": "https://app.byperform.co.il/studio-fit/clients/cm2k9x1ab0001l508u3f7q2wd?tab=nutritionPlans"
  },
  "subscriptions": [
    {
      "id": "cm3f1c4ij0015l908o9j2p6kg",
      "planName": "3 months",
      "status": "ACTIVE",
      "startedOn": "2026-09-01T00:00:00.000Z",
      "endsOn": "2026-12-01T00:00:00.000Z",
      "priceAgorot": 90000,
      "planFrozenOn": null,
      "planRemainingDays": null,
      "canceledOn": null,
      "createdAt": "2026-09-01T08:00:00.000Z"
    }
  ],
  "weeksInProcess": 5.1,
  "today": {
    "mode": "grams",
    "protein": { "current": 96, "goal": 160 },
    "carbs": { "current": 130, "goal": 210 },
    "fat": { "current": 38, "goal": 65 },
    "steps": { "current": 6200, "goal": 10000 },
    "stepsAvg7d": 7840
  },
  "targets": { "kcal": 2100, "protein": 160, "carbs": 210, "fat": 65 },
  "training": { "workoutsPerWeek": 4, "activeProgramId": "cm2q3w7ya000al908c6t1n4xb", "programName": "Strength block A" },
  "counters": { "updateFormsCount": 5, "lastUpdateFormAt": "2026-10-05T07:00:00.000Z" },
  "weeklyRating": { "value": 4, "max": 5, "submittedAt": "2026-10-05T07:00:00.000Z" },
  "weight": {
    "first": { "weightKg": 75, "recordedAt": "2026-09-01T05:30:00.000Z" },
    "latest": { "weightKg": 71.4, "recordedAt": "2026-10-07T05:41:00.000Z" },
    "changePercent": -4.8
  },
  "photos": {
    "intake": { "front": "https://cdn.example.com/media/a.jpg", "side": null, "back": null, "weightKg": 75, "date": "2026-09-01T09:00:00.000Z" },
    "latest": { "front": "https://cdn.example.com/media/b.jpg", "side": null, "back": null, "weightKg": 71.4, "date": "2026-10-05T07:00:00.000Z" }
  },
  "latestCheckin": {
    "responseId": "cm3b3u6ef000xl908g1b4h8cy",
    "submittedAt": "2026-10-05T07:00:00.000Z",
    "answers": [
      { "label": "Energy this week", "value": "4 / 5", "type": "rating" },
      { "label": "Notes", "value": "Felt strong", "type": "text" }
    ]
  }
}

number | null

The latest weigh-in, falling back to the profile value.

string | null

The latest of lastCheckInAt, the newest form response and the client’s updatedAt.

object

Built from APP_WEB_URL, the studio slug and the trainee id.

array

Every subscription of the trainee, newest startedOn first, in any status.

number | null

Weeks since the running (ACTIVE or FROZEN) subscription started, to one decimal.

string

grams or mbp. In mbp mode (studio portion system on) the protein, carbs and fat numbers and targets are in portion units and targets.kcal is the sum of the three. In grams mode values are rounded to whole numbers.

number | null

The trainee’s own stepsGoal. stepsAvg7d averages the days of the last 7 that have a step value.

object | null

Today’s plan-day targets. null with no regular nutrition plan.

object

Count and latest date of submitted check-in forms.

object

The first numeric rating answer of the latest check-in, with its star count. All null when there is none.

object

intake comes from posed photos of the first intake response, latest from the newest check-in that has posed photos. When either is missing, posed photos that are not tied to a form are used: the earliest day for intake, the latest for latest, with the nearest weigh-in within 60 days as the weight. Either can be null.

array

Only text, number and rating answers of the latest check-in, formatted as on the web response page.

Today’s nutrition numbers use the same math as the trainee’s home screen: the saved day snapshot priced against the plan, plus free meal logs that the snapshot does not already account for. Errors: NOT_FOUND (404) trainee not found or studio not found.

`GET /v1/partner/trainees/:id/workouts`

Lists the trainee’s workout logs, completed or not, with exercises and sets. Auth: studio API key.

string

required

The trainee id.

number

default:"1"

Positive integer.

number

default:"20"

Positive integer, at most 100.

Exercise names are resolved from the library by exerciseId, falling back to the name stored in the log entry, then to a generic Hebrew placeholder. Sets explicitly marked done: false are left out. Response: 200.

{
  "items": [
    {
      "id": "cm2r5k1pc000dl908w2e8z7mf",
      "performedOn": "2026-10-07T16:40:12.000Z",
      "label": "A",
      "durationSec": 3120,
      "completed": true,
      "exercises": [
        { "name": "Bench press", "sets": [{ "weight": 60, "reps": 10 }, { "weight": 60, "reps": 9 }] }
      ]
    }
  ],
  "total": 37,
  "page": 1,
  "pageSize": 20
}

Errors: VALIDATION (422) for bad paging values. NOT_FOUND (404) trainee not found.

`GET /v1/partner/trainees/:id/nutrition-days`

Returns consumed and target macros per day for a date range. Auth: studio API key.

string

required

The trainee id.

string

required

YYYY-MM-DD.

string

required

YYYY-MM-DD. Not before from. The range may span at most 62 days.

Every day in the range is returned, including days with nothing logged. Each day maps to a plan day by its offset from today in the trainee’s zone, using the newest active nutrition plan as it is now. Past days are therefore priced against the current plan, not the plan that was active then. Response: 200.

{
  "days": [
    {
      "date": "2026-10-06",
      "mode": "grams",
      "consumed": { "kcal": 1980, "protein": 152, "carbs": 198, "fat": 61 },
      "target": { "kcal": 2100, "protein": 160, "carbs": 210, "fat": 65 }
    },
    {
      "date": "2026-10-07",
      "mode": "grams",
      "consumed": { "kcal": 1240, "protein": 96, "carbs": 130, "fat": 38 },
      "target": { "kcal": 2100, "protein": 160, "carbs": 210, "fat": 65 }
    }
  ]
}

target is null with no regular nutrition plan. In mbp mode all four numbers are portion units, as on the overview. Errors:

Code	Status	When
`VALIDATION`	422	`from` or `to` missing or not `YYYY-MM-DD`
`BAD_REQUEST`	400	`from must not be after to`, or `range must not exceed 62 days`
`NOT_FOUND`	404	`trainee not found` or `studio not found`

`GET /v1/partner/trainees/:id/forms`

Lists the trainee’s form responses. Auth: studio API key.

string

required

The trainee id.

Response: 200.

{
  "items": [
    {
      "responseId": "cm3b3u6ef000xl908g1b4h8cy",
      "formTemplateId": "cm1f3a2bc0005",
      "formName": "Weekly check-in",
      "formType": "CHECK_IN",
      "submittedAt": "2026-10-05T07:00:00.000Z"
    }
  ]
}

formName is the coach-facing template name. Errors: NOT_FOUND (404) trainee not found.

`GET /v1/partner/trainees/:id/forms/:responseId`

Returns one form response with every answer formatted for display. Auth: studio API key.

string

required

The trainee id.

string

required

The form response id.

Answers are built from the response’s own schema snapshot, so they reflect the form as it was when answered. Display-only blocks are skipped. Formatting (formatAnswerValue):

Field type	`value`
Empty answer	`-`
`checkbox_confirmation`	A Hebrew “confirmed” or “not confirmed” string
`gender`	The Hebrew label
`dropdown`, `goal`	The option label, or labels joined with a comma
`rating`	`4 / 5`
`image_upload`, `video_upload`	The raw URL
Anything else	The value as a string. Objects are JSON encoded

Response: 200.

{
  "responseId": "cm3b3u6ef000xl908g1b4h8cy",
  "formName": "Weekly check-in",
  "formType": "CHECK_IN",
  "submittedAt": "2026-10-05T07:00:00.000Z",
  "answers": [
    { "label": "Current weight", "value": "71.4", "type": "weight" },
    { "label": "Energy this week", "value": "4 / 5", "type": "rating" },
    { "label": "Front photo", "value": "https://cdn.example.com/media/b.jpg", "type": "image_upload" }
  ]
}

Errors: NOT_FOUND (404) trainee not found or form response not found.

`GET /v1/partner/trainees/:id/weights`

Lists every weigh-in of the trainee. Auth: studio API key.

string

required

The trainee id.

Response: 200.

{
  "items": [
    { "recordedAt": "2026-09-01T05:30:00.000Z", "weightKg": 75, "source": "form" },
    { "recordedAt": "2026-10-07T05:41:00.000Z", "weightKg": 71.4, "source": "APP" }
  ]
}

source is the stored value: APP, form, COACH, automation, an autofit marker or null for old rows. Errors: NOT_FOUND (404) trainee not found.

`GET /v1/partner/trainees/:id/programs`

Returns the trainee’s newest active program of one type, rendered for display. Auth: studio API key.

string

required

The trainee id.

string

required

TRAINING or NUTRITION.

Response: 200. With no active program of that type the body is { "program": null }. A training program:

{
  "program": {
    "id": "cm2q3w7ya000al908c6t1n4xb",
    "name": "Strength block A",
    "status": "ACTIVE",
    "startsOn": "2026-09-01T00:00:00.000Z",
    "endsOn": null,
    "editUrl": "https://app.byperform.co.il/studio-fit/clients/cm2k9x1ab0001l508u3f7q2wd/programs/cm2q3w7ya000al908c6t1n4xb/edit",
    "pdfUrl": null,
    "days": [
      {
        "label": "A",
        "exercises": [{ "name": "Bench press", "sets": 3, "reps": "8-12", "equipment": "Barbell" }]
      }
    ]
  }
}

A nutrition program has the same top level, with days shaped like this:

{
  "label": "יום 1",
  "targets": { "kcal": 2100, "protein": 160, "carbs": 210, "fat": 65, "water": 3 },
  "meals": [
    {
      "time": "08:00",
      "label": "ארוחת בוקר",
      "items": [{ "name": "Oats", "display": "60 גרם" }]
    }
  ]
}

A file plan returns pdfUrl and days: []. sets is the number of set rows, or the row’s sets value. display is the ready-made quantity text, or null for foods without display unit data. Unknown exercises and foods get generic Hebrew placeholder names. Errors: VALIDATION (422) when type is missing or invalid. NOT_FOUND (404) trainee not found or studio not found.

`GET /v1/partner/trainees/:id/tasks`

Lists the open coach tasks about this trainee. Auth: studio API key.

string

required

The trainee id.

Returns InboxItem rows with status OPEN or SNOOZED, newest first. Response: 200.

{
  "items": [
    {
      "id": "cm3g3e6jk0017l908q1l4r8mi",
      "type": "FORM_FILLED",
      "title": "Weekly check-in submitted",
      "detail": null,
      "dueAt": null,
      "priority": 1,
      "status": "OPEN"
    }
  ]
}

Errors: NOT_FOUND (404) trainee not found.

Subscription actions

`POST /v1/partner/trainees/:id/freeze`

Freezes the trainee’s running plan. Auth: studio API key.

string

required

The trainee id.

No body. The call goes through the same ClientSubscriptionsService.freeze the coach web app uses, with the API key id as the actor and the same notifier wiring. An AuditLog row with action partner.freeze is written. Response: 200.

{
  "ok": true,
  "subscription": {
    "id": "cm3f1c4ij0015l908o9j2p6kg",
    "planName": "3 months",
    "status": "FROZEN",
    "startedOn": "2026-09-01T00:00:00.000Z",
    "endsOn": "2026-12-01T00:00:00.000Z",
    "priceAgorot": 90000,
    "planFrozenOn": "2026-10-07T12:00:00.000Z",
    "planRemainingDays": 55,
    "canceledOn": null,
    "createdAt": "2026-09-01T08:00:00.000Z"
  }
}

subscription is the trainee’s FROZEN subscription after the call, or null if none is found. Errors:

Status	Body	When
409	`{ "error": { "code": "FREEZE_REJECTED", "message": "..." } }`	The subscription service refused with a `VALIDATION` or `CONFLICT` error, for example `plan is already frozen` or `client has no active plan`
404	Standard envelope, `NOT_FOUND`	`trainee not found`

`POST /v1/partner/trainees/:id/reactivate`

Reactivates a frozen plan. Auth: studio API key.

string

required

The trainee id.

No body. Mirrors the freeze call through ClientSubscriptionsService.reactivate and writes an AuditLog row with action partner.reactivate. Response: 200 with { "ok": true, "subscription": { ... } }, where subscription is the trainee’s ACTIVE subscription after the call. Errors: 409 FREEZE_REJECTED, for example plan is not frozen. The error code is FREEZE_REJECTED for both actions. 404 trainee not found.

Activity and notes

`GET /v1/partner/trainees/:id/activity`

Returns the trainee’s activity feed, the same one the coach sees on the trainee card. Auth: studio API key.

string

required

The trainee id.

string

The partner-side user id of the person viewing, 1 to 80 characters. When given, the response includes the actor id that user maps to, so the client can tell which notes are theirs to delete.

The feed is assembled by assembleActivity in the clients service from recorded coach actions plus the trainee’s own meals, completed workouts, form responses and technique videos. Response: 200.

{
  "activity": [
    {
      "id": "cm3h5g8kl0019l908s3n6t0ok",
      "actorId": "smartsend:u_812",
      "actorType": "COACH",
      "actorName": "SmartSend · Dana",
      "type": "COACH_NOTE",
      "action": null,
      "entityType": null,
      "entityId": null,
      "entityName": null,
      "metadata": { "note": "Asked to move the check-in to Sunday" },
      "occurredAt": "2026-10-07T12:10:00.000Z"
    },
    {
      "id": "workout:cm2r5k1pc000dl908w2e8z7mf",
      "actorType": "TRAINEE",
      "actorName": null,
      "type": "WORKOUT_COMPLETED",
      "action": null,
      "entityType": "WORKOUT",
      "entityId": "cm2q3w7ya000al908c6t1n4xb",
      "entityName": "A",
      "metadata": null,
      "occurredAt": "2026-10-07T16:40:12.000Z"
    }
  ],
  "viewerActorId": "smartsend:u_812"
}

The first entry is a note. Its text is in metadata.note. The type and actorType strings shown for it are illustrative: the stored values come from COACH_NOTE_ACTIVITY_TYPE and recordActivity in the clients module. Derived entries use prefixed ids: workout:, form: and video:. For those, entityId is the program or form template id, not the log id. viewerActorId is null without viewer. Errors: VALIDATION (422) when viewer is empty or too long. NOT_FOUND (404) trainee not found.

`POST /v1/partner/trainees/:id/activity/notes`

Adds a note to the trainee’s timeline on behalf of a partner-side user. Auth: studio API key.

string

required

The trainee id.

string

required

At most 10,000 characters. Must not be blank after trimming.

object

required

Who is writing.

string

required

The partner-side user id. Trimmed, 1 to 80 characters.

string

Display name. Trimmed, at most 120 characters.

How the author is resolved (resolvePartnerActor):

The studio’s settings.smartsend.userMap maps Perform coach ids to SmartSend users. If author.id matches a mapped user and that coach has an externalUserId, the note is written as that coach. The coach can then see and delete it inside Perform too.
Otherwise the note is written under the actor id smartsend:<author.id> and labelled SmartSend · <author.name>, or just SmartSend without a name.

An AuditLog row with action partner.activity_note.create records the API key. Response: 201.

{ "id": "cm3h5g8kl0019l908s3n6t0ok", "occurredAt": "2026-10-07T12:10:00.000Z" }

Errors: VALIDATION (422) when the body fails the schema or the text is blank (note text is required). NOT_FOUND (404) trainee not found or studio not found.

`DELETE /v1/partner/trainees/:id/activity/notes/:activityId`

Deletes a note. Only its author can delete it. Auth: studio API key.

string

required

The trainee id.

string

required

The note’s activity id.

string

required

The partner-side user id of the person deleting, 1 to 80 characters. Resolved to an actor the same way as on create.

An AuditLog row with action partner.activity_note.delete is written. Response: 200.

{ "deleted": true }

Errors:

Code	Status	When
`VALIDATION`	422	`author` missing
`NOT_FOUND`	404	`trainee not found`, or `note not found`
`FORBIDDEN`	403	`only the author can delete a note`

Audience reports

Reports return lists of trainees for SmartSend’s campaign wizard. A report’s clients become a mailing list, and every context key becomes a per-recipient field usable as a template variable. Rules for every report (reports.service.ts, reports.repository.ts):

Only clients with status ACTIVE and no deletedAt are considered. Frozen, paused and archived trainees are never part of a messaging audience.
Clients with no digits in their phone are skipped and counted in skippedNoPhone.
phoneNumber is international digits without a plus sign. A local number starting with 0 becomes 972 plus the rest.
Names: firstName and lastName when stored, else the full name split on the first space.
context values are flat strings or numbers. A key is omitted when it has no value.
A report whose base filter matches more than 20,000 clients returns 400 report too large.
Rows are ordered by name.

`GET /v1/partner/reports`

Returns the static report catalog. SmartSend renders its picker from it, so a new report added in reports.schema.ts appears there without a SmartSend deploy. Auth: studio API key. Response: 200.

{
  "reports": [
    {
      "key": "workout-goal",
      "description": "יעד אימונים שבועי: עמדו או לא עמדו ביעד בשבעת הימים האחרונים",
      "params": [{ "name": "segment", "type": "string", "required": true, "enum": ["reached", "not_reached"] }],
      "context": ["name", "coachName", "workoutsThisWeek", "weeklyGoal"]
    },
    {
      "key": "birthdays",
      "description": "מתאמנים שחוגגים יום הולדת היום",
      "context": ["name", "coachName", "birthDate", "age"]
    }
  ]
}

The catalog has five entries: workout-goal, inactive, plan-expiry, birthdays and open-forms. Descriptions are in Hebrew. params is omitted for reports without parameters. Errors: none beyond the lane errors.

`GET /v1/partner/reports/:key`

Runs one report. Auth: studio API key.

string

required

workout-goal, inactive, plan-expiry, birthdays or open-forms.

Query parameters and meaning per report:

Key	Parameters	Who is included	`context` keys
`workout-goal`	`segment` required: `reached` or `not_reached`	`reached`: 3 or more workout logs in the last 7 days (`WEEKLY_GOAL = 3`). `not_reached`: everyone else, including zero	`name`, `coachName`, `workoutsThisWeek`, `weeklyGoal`
`inactive`	`days` optional, integer 1 to 90, default 7	`lastCheckInAt` older than `days` days. A trainee who never opened the app is included only when they were created more than `days` days ago	`name`, `coachName`, `daysInactive`, `lastCheckInDate` (both only when the trainee has opened the app)
`plan-expiry`	`status` required: `expiring` or `expired`. `days` optional, integer 1 to 90, default 21	`expired`: `endsOn` at or before now and no `SCHEDULED` subscription. `expiring`: `endsOn` after now and within `days` days, and no `SCHEDULED` subscription that ends beyond that horizon	`name`, `coachName`, `planName`, `endsOnDate`, `daysRemaining`
`birthdays`	None	`birthDate` month and day equal today’s in the studio’s time zone	`name`, `coachName`, `birthDate`, `age`
`open-forms`	None	At least one `PENDING` form assignment	`name`, `coachName`, `pendingFormNames`, `pendingFormCount`

Notes:

workout-goal counts every workout log in the window, whether or not it is marked completed. The goal is the constant 3, not the trainee’s plan frequency.
plan-expiry reports endsOnDate and daysRemaining from the coverage end, which includes queued plans.
The days parameter of plan-expiry is validated for expired too, but only used for expiring.

Response: 200.

{
  "report": "workout-goal",
  "clients": [
    {
      "id": "cm2k9x1ab0001l508u3f7q2wd",
      "firstName": "Noa",
      "lastName": "Cohen",
      "phoneNumber": "972500000000",
      "email": "noa@example.com",
      "gender": "FEMALE",
      "context": { "name": "Noa Cohen", "coachName": "Dana Levi", "workoutsThisWeek": 2, "weeklyGoal": 3 }
    }
  ],
  "total": 41,
  "skippedNoPhone": 3
}

total is the number of clients returned, after skipping those without a phone. Errors:

Code	Status	When
`VALIDATION`	422	Unknown `key`, a missing required parameter, or `days` out of range
`BAD_REQUEST`	400	`report too large`

Differences from the older notes

backend/docs/PARTNER_REPORTS.md predates some of the code. Where they differ, the code above is right:

inactive accepts days from 1, not 3.
inactive does not include every trainee who never checked in. New trainees are excluded until they are older than the window.
birthdays uses the studio’s time zone, not UTC.
plan-expiry excludes trainees who already have a scheduled follow-up plan.
The catalog description strings no longer contain a dash.

​Conventions on this lane

​API keys

​GET /v1/web/studios/current/api-keys

​POST /v1/web/studios/current/api-keys

​POST /v1/web/studios/current/api-keys/:id/revoke

​Connection

​GET /v1/partner/ping

​Finding a trainee

​GET /v1/partner/trainees/by-phone/:phone

​Reading a trainee

​GET /v1/partner/trainees/:id/overview

​GET /v1/partner/trainees/:id/workouts

​GET /v1/partner/trainees/:id/nutrition-days

​GET /v1/partner/trainees/:id/forms

​GET /v1/partner/trainees/:id/forms/:responseId

​GET /v1/partner/trainees/:id/weights

​GET /v1/partner/trainees/:id/programs

​GET /v1/partner/trainees/:id/tasks

​Subscription actions

​POST /v1/partner/trainees/:id/freeze

​POST /v1/partner/trainees/:id/reactivate

​Activity and notes

​GET /v1/partner/trainees/:id/activity

​POST /v1/partner/trainees/:id/activity/notes

​DELETE /v1/partner/trainees/:id/activity/notes/:activityId

​Audience reports

​GET /v1/partner/reports

​GET /v1/partner/reports/:key

​Differences from the older notes

Conventions on this lane

API keys

`GET /v1/web/studios/current/api-keys`

`POST /v1/web/studios/current/api-keys`

`POST /v1/web/studios/current/api-keys/:id/revoke`

Connection

`GET /v1/partner/ping`

Finding a trainee

`GET /v1/partner/trainees/by-phone/:phone`

Reading a trainee

`GET /v1/partner/trainees/:id/overview`

`GET /v1/partner/trainees/:id/workouts`

`GET /v1/partner/trainees/:id/nutrition-days`

`GET /v1/partner/trainees/:id/forms`

`GET /v1/partner/trainees/:id/forms/:responseId`

`GET /v1/partner/trainees/:id/weights`

`GET /v1/partner/trainees/:id/programs`

`GET /v1/partner/trainees/:id/tasks`

Subscription actions

`POST /v1/partner/trainees/:id/freeze`

`POST /v1/partner/trainees/:id/reactivate`

Activity and notes

`GET /v1/partner/trainees/:id/activity`

`POST /v1/partner/trainees/:id/activity/notes`

`DELETE /v1/partner/trainees/:id/activity/notes/:activityId`

Audience reports

`GET /v1/partner/reports`

`GET /v1/partner/reports/:key`

Differences from the older notes