Skip to main content

List clients

Required scope:
Query parameters:
Response:
Client list and detail items include your own externalReference object or null. See External references for binding existing clients, editing references and permanently deduplicating creation.

Get a client

Required scope:
The response includes safe Core CRM fields such as name, email, phone number, relationship status, assigned coach, location, language, timezone, and custom fields. It does not expose passwords, devices, payment data, notes, chats, or subscriptions.

Client output fields

List responses return pagination fields plus data.data[]. Detail responses return data.client.

Client statuses and app access

Company status automation

GET /public/v1/clients/status-automation requires client_status_automation:read and returns the effective statusAutomation rules and preserveManualStatuses flag. Existing company choices override these defaults: Every event accepts keep_status, set_trial, set_active, set_paused, set_inactive or set_archived. preserveManualStatuses defaults to true: an explicit manual status remains protected when this flag is enabled. Membership pause and end rules account for the member’s other memberships. Default rules do not move an inactive member back to trial, active or paused, including a pause/resume cycle. Moving an inactive member to one of these statuses requires an explicitly saved event rule. The legacy active-product opt-in remains effective. PATCH /public/v1/clients/status-automation requires the separately granted client_status_automation:write scope and an Idempotency-Key header. Existing clients:write grants do not include company automation management. The OAuth client creator must retain active company access and access.settings.update; standard authorization mode requires an Admin. Current permissions are checked for every policy write. Supply one or more event rules or the manual-status protection flag; omitted rules and other company settings are preserved. The update applies to future lifecycle events and does not change existing members in bulk.
Unknown fields, event names or actions return 400; missing scopes return 403. A reused idempotency key with different input returns 409. Normal API rate limits apply; observe Retry-After after 429. Client list and detail responses include relationship.statusMode as automatic or manual. GET /public/v1/clients/{clientId}/timeline requires client_timeline:read and includes recorded status_changed items. Their statusChange contains fromStatus, toStatus, source (automatic, coach, integration or system), event, UTC changedAt and a nullable changedByCoachId. A mode-only change can keep the same status. Earlier changes may have no recorded history. The timeline retains its normal pagination. These fields describe the relationship between a client and the authenticated company. They do not describe a global account status or an external payment. The same client can have a different relationship with another company.

Relationship status

Client list/detail responses use relationship.status. Lifecycle and portal responses name the same field relationshipStatus. Normal company-scoped client reads exclude removed, rejected and blocked relationships, as well as erased or anonymized company data. A status query filter does not override that visibility rule.

Member status

relationship.memberStatus describes the membership classification separately from the relationship stage. It is not proof of a paid invoice or app access.

Portal access status

relationship.portalAccessStatus records the portal access state. Company lifecycle policy and any required external grant also apply to actual access. These tables list the canonical lifecycle values. Older records without a stored value can return an empty string; do not infer access from that value.

Supported changes

Paths in this table start at /public/v1. Each operation retains its documented scopes; see the sections below and External client access. Use the lifecycle operation to activate, pause or resume an operational relationship. Onboarding, archive and removal states retain their dedicated workflows. PATCH /clients/{clientId} supports the profile, coach and tag fields documented below; lifecycle fields belong to the separate /lifecycle operation. Do not use relationship.status: "active", memberStatus: "active" or portalAccessStatus: "enabled" alone as proof of app access. For example, an externally managed client can remain active with portal access enabled while the required app grant has expired. Read the current effective access response.

Create a client

Required scope:
If assignedCoach is omitted, FITsociety uses the OAuth client’s defaultAssignedCoachId. If neither is available, the request fails with ASSIGNED_COACH_REQUIRED. Set hasNoEmail to true to generate a placeholder email address. Request validation:
Response (201 Created):
New-client responses return: Existing-account responses return: If the existing client is already connected to the company, the endpoint returns 409 CLIENT_ALREADY_EXISTS_IN_COMPANY.

Update a client

Required scope:
Supported update fields:

Change operational status and portal access

Required scope: clients:write. Supply at least one of these fields; unknown fields and direct memberStatus input are rejected. The current relationship must also be trial, active, paused or inactive. This operation cannot approve an invitation or pending registration, reactivate an archived/removed relationship, bypass a block, or restore deleted, rejected, erased or anonymized company data. Use the relevant onboarding or archive operation, or contact the company administrator for those cases. Pause and disable portal access together:
Resume with a new logical request and idempotency key:
The response returns data.lifecycle with clientId, relationshipStatus, memberStatus, portalAccessStatus, archivedAt and archiveReason. Archive metadata and historical relationship dates are preserved. A no-op succeeds without another write or webhook. A changed state emits client.updated with changed.lifecycle: true; a changed portal state also emits client.portal_access.changed. This is a status edit, not a new link or membership activation. It does not clear an existing relationshipEndDate or inactivity metadata; those values can continue to affect other company features and client counting. Status edits set relationshipStatusMode to manual by default. When the company preserves manual statuses, automatic membership rules leave that status unchanged. Send {"relationshipStatusMode":"automatic"} to the same lifecycle endpoint with a new idempotency key to resume company rules at the next reconciliation. Send {"relationshipStatusMode":"manual"} to protect the current status without changing it. Explicit portal access restrictions remain independent. Changing status alone does not automatically disable or enable the portal. A paused relationship follows the company’s configured access policy. Use portalAccessStatus: "disabled" when portal access must stop. Conversely, enabled does not guarantee usable app access: company policy and any required external app grant still apply. Read GET /clients/{clientId}/access-entitlements with client_access:read for the current effective result. This lifecycle write does not mutate external grants, manual AI rights, payments or subscriptions. Invalid input returns 400, an inaccessible client 404, and a protected transition or concurrent update 409. After a conflict, read current state and reconcile before retrying; do not blindly overwrite a concurrent suspension. The normal HTTP idempotency contract applies. A replay is a response snapshot, so read current state when you need the latest status or effective access.

Archive a client

Required scope:
Archive is a lifecycle transition, not a hard delete. FITsociety sets the company relationship to archived, member status to past, and portal access status to disabled. Response fields: Validation: The response does not expose archivedBy, removal outcomes, deletion flags, or private retention metadata.

Portal access and onboarding

Required scopes: clients:read for portal-access, client_onboarding:write for invites and relationship rejection. GET /portal-access returns the current company-client portal access status without exposing auth state, sessions, devices, password status, or identity tokens. Portal access response fields: Invite endpoints validate that the client belongs to the authenticated company and has a real email address. Placeholder email accounts cannot be invited. The endpoints send a portal invitation and return: Relationship rejection is available for clients whose company relation is pending_approval. Reject request body: Relationship rejection response fields: Not exposed: reviewed-by coach ID, auth tokens, password state, private notes, or deletion metadata.

Custom field definitions

Required scope:
Returns active custom fields that are visible on the client page. Hidden fields, inactive fields, usage flags, private update metadata, and validation regex patterns are not exposed. Omitting page and limit returns the first 10 visible definitions in configured display order. Collection reads always use 1-based pagination, with a default page of 1, a default limit of 10, and a maximum limit of 100. Paginated results sort by display order, then stable field key. Visibility is applied before the total and page are calculated.
The data.customFields array keeps the same definition fields in both modes. Paginated responses also include data.page, data.limit, data.total, data.totalPages, data.hasNextPage, and data.hasPrevPage. totalPages is at least 1; a page beyond the end returns an empty array. Continue increasing page while hasNextPage is true. Pagination on this endpoint does not paginate a client’s custom field values. Definition fields:

Manage the shared field library

The full shared field library has separate permissions from member values: Existing client_custom_fields:read and client_custom_fields:write grants do not grant library management. Company scope is determined by the access token. All writes require an Idempotency-Key; a same-key, same-request retry replays its response. Normal connection rate limits apply; see contracts. No member values are rewritten by library management. The library read includes hidden and inactive definitions. It uses 1-based pagination, defaults to 10 definitions per page and allows at most 100. Read hasNextPage to continue. Responses contain page, limit, total, totalPages, hasNextPage, hasPrevPage and customFields, ordered by order then key. No member values or update-author metadata are returned.
Create requires key, label and type. The response is data.customField, the complete normalized definition. Use these properties: Patch accepts at least one property except key. Unspecified properties are preserved. Nested localized texts, usage, validation and sequence settings are merged; options replaces the entire option list. For example:
Automatic numbering fields normalize to optional text (or hidden), return readOnly: true and are excluded from registration, membership-change and cancellation forms. A prefix LID with padding 4 produces LID-0001. Changing numbering settings never rewrites existing member values. The next-number setting can advance the counter but cannot move an allocated counter backwards. It is a configured lower bound, not a live counter reading. Delete accepts no body and returns data: {key, deleted: true, retained}. If members have recorded values, retained is true: the definition becomes inactive and hidden, with every usage flag false. Values remain stored. An unused definition is removed and retained is false. Numbering counters are preserved. To restore a retained definition, patch active: true plus the intended mode and usage flags. Invalid keys, types, options or unknown properties return 400; unknown keys in the current company return 404. Duplicate keys or a concurrent library edit return 409. After a concurrent-edit conflict, read the current library and retry with a new idempotency key. Missing scopes return 403. Errors use the standard error envelope.

Client custom field values

Required scopes: client_custom_fields:read for reads, client_custom_fields:write for writes. Patch body:
Value response fields: Validation:

Assigned coaches

Required scopes: clients:read for reads, clients:write for writes. Patch body:
Set coachId to null or an empty value to clear the assignment. Response fields: Writes validate that the coach exists and has active access to the company. Coach email, phone number, last active data, roles, and auth/device fields are not returned.

Client timeline

Required scope:
Timeline is intentionally limited to sanitized lifecycle events. It excludes notes, provider payloads, workout/nutrition events, raw audit logs, payment provider data, private deletion metadata, and retention details. Response fields: Validation:
DELETE /public/v1/clients/{clientId} is not exposed in v1. Use the archive endpoint to archive the company-client relationship.

Client tags

Required scope:
Use this endpoint to fetch tag IDs before creating or updating clients. Omitting page and limit returns the first 10 company tags in name and tag ID order. Lists always use 1-based pagination, with a default page of 1, a default limit of 10, and a maximum limit of 100. Company scope and deleted-tag filtering apply before the total and page are calculated.
The data.data array keeps the same tag fields in both modes. Paginated responses also include data.page, data.limit, data.total, data.totalPages, data.hasNextPage, and data.hasPrevPage. totalPages is at least 1; a page beyond the end returns an empty array. Continue increasing page while hasNextPage is true. Response fields: Deleted tags, hidden relationship statuses, and removed client outcomes are not included in the counts.