Requests and errors

Use the parameters and body schema of the specific operation in the API reference. A parameter example is not a default: required parameters must be sent on every request.

Pagination and filters

For pageSize / pageNum pagination, use a page size of 1–50 and start at page 1. These parameters have no defaults. Paginated responses contain a docs array and pagination metadata such as hasNextPage and nextPage. Other list endpoints may return an array; there is no universal limit / offset convention. Activity feed requires page >= 1 and limit from 1–100.

Use lowercase true or false for boolean query values. Legacy v1 primitive query conversion coerces supplied values such as archived=yes to false. Numeric query values are also converted before integer validation: for example, pageNum=1e0&pageSize=2e1 is accepted as page 1 with 20 items. These are existing behaviors; use explicit booleans and decimal integers in integrations. Pass dates as YYYY-MM-DD, for example 2026-05-15. Object identifiers are 24 hexadecimal characters, for example 60626cc191f3a274116fee34.

Repeat customer group and trainer filters to supply multiple values:

/coach/customers?archived=false&pageSize=20&pageNum=1&groups=Strength&groups=Mobility&assignedTo=none

Groups and assigned trainers use OR matching within each filter. none includes customers without an assigned trainer. Commas in a customer group name are literal, not separators. URL-encode names and other user-entered values; let your HTTP client build the query string.

Bodies and uploads

Send JSON with Content-Type: application/json, using the documented field names. For example, creating an exercise workout item requires type and uses exerciseSets, not sets. Type-specific fields such as taskFields, metricsFields and form are required for the corresponding item type.

Bulk customer operations require a selection containing either ids or filter; excludeIds can accompany filter only. A filter must specify archived. Unknown fields are rejected for bulk operations. A bulk response reports requested, ok and per-customer failed entries; inspect these even when the HTTP status indicates success.

Use multipart/form-data for uploads and let your client set the multipart boundary. The nutrition plan file field is file; progress photos use imageFile; profile photos use profilePhotoFile. Progress photo creation also requires createdAt and a numeric string imageSideIndex ("1" front, "2" back, "3" side). Replacing a progress photo requires imageFile and imageSideIndex. Progress photo creation accepts a request without a new image file; profile photo updates also accept an omitted file. A JSON body cannot carry a binary file. Missing files are not consistently rejected by validation; a nutrition-plan upload without file can return 500.

Errors

Missing or invalid integer query parameters can return this generic error, which does not identify the field:

{
  "statusCode": 400,
  "message": "Validation failed (numeric string is expected)",
  "error": "Bad Request"
}

For GET /coach/customers, check that archived, pageSize and pageNum are all present. Missing boolean query values can instead produce Validation failed (boolean string is expected). When several parameters are invalid or missing, the response may report only one failure; do not assume it identifies the first parameter in the URL.

DTO validation may return message as an array, for example:

{
  "statusCode": 400,
  "message": ["email must be an email"],
  "error": "Bad Request"
}

Legacy errors can instead return { "code": "...", "message": "..." }; API-key middleware can return only message. Handle the HTTP status first, retain a supplied code, and avoid depending on an exact English sentence. If several fields are invalid, the server may report one at a time. Some existing request failures return 500 rather than a field validation error: examples include malformed personal-record identifiers, a missing metrics set, and a workout-item move without source or target. A 500 therefore does not always indicate a transient failure. Database errors may include the database error message; treat error text as diagnostic information rather than a stable schema or a message safe for public display.

For the customers list in Make, use GET, retain the X-API-Key header, and set archived=false, pageSize=20, pageNum=1 as query parameters. Do not put these parameters in a GET body.