List clients
externalReference object or null.
See External references for binding existing
clients, editing references and permanently deduplicating creation.
Get a client
Client output fields
List responses return pagination fields plusdata.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.
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 userelationship.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
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:
201 Created):
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
Change operational status and portal access
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:
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
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
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
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.
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.
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:
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
client_custom_fields:read for reads,
client_custom_fields:write for writes.
Patch body:
Validation:
Assigned coaches
clients:read for reads, clients:write for writes.
Patch body:
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
Validation:
Client tags
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.
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.