Clients

List clients

GET /public/v1/clients
Authorization: Bearer <access_token>

Required scope:

clients:read

Query parameters:

Parameter	Type	Notes
`page`	integer	1-based page number
`limit`	integer	Defaults to 100, maximum 500
`search`	string	Searches first name, last name, and email
`status`	string	Optional relationship status filter

curl -H "Authorization: Bearer <access_token>" \
  "https://api.fitsociety.io/public/v1/clients?limit=50&search=jane"

Get a client

GET /public/v1/clients/{clientId}
Authorization: Bearer <access_token>

Required scope:

clients:read

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.

Field	List	Detail	Type	Nullable	Description
`clientId`	yes	yes	string	no	Client ID.
`firstName`	yes	yes	string	no	First name.
`lastName`	yes	yes	string	no	Last name.
`email`	yes	yes	string	no	Email, empty for placeholder email accounts.
`emailIsPlaceholder`	yes	yes	boolean	no	Whether FITsociety generated a placeholder email.
`relationship.status`	yes	yes	string	no	Company relationship status.
`relationship.memberStatus`	yes	yes	string	no	Member status.
`relationship.portalAccessStatus`	yes	yes	string	no	Portal access status.
`relationship.assignedCoach.name`	yes	yes	string	no	Assigned coach name when available.
`relationship.assignedCoach.coachId`	no	yes	string	no	Assigned coach ID.
`relationship.startedAt`	no	yes	string	yes	Relationship start date.
`phoneNumber`	no	yes	string	no	Phone number.
`gender`	no	yes	string	no	Gender field.
`dateOfBirth`	no	yes	string	yes	Date of birth.
`language`	no	yes	string	no	Client language.
`lastActiveAt`	no	yes	string	yes	Last activity timestamp.
`createdAt`	no	yes	string	yes	Client creation timestamp.
`location.addressLine1`	no	yes	string	no	Address line.
`location.addressLine2`	no	yes	string	no	Address line.
`location.zipCode`	no	yes	string	no	ZIP/postal code.
`location.city`	no	yes	string	no	City.
`location.country`	no	yes	string	no	Country.
`height`	no	yes	string	no	Height as stored.
`timeZone`	no	yes	string	no	IANA timezone.
`profession`	no	yes	string	no	Profession.
`companyName`	no	yes	string	no	Client company name.
`customFields[].key`	no	yes	string	no	Custom field key.
`customFields[].label.en`	no	yes	string	no	English label snapshot.
`customFields[].label.nl`	no	yes	string	no	Dutch label snapshot.
`customFields[].type`	no	yes	string	no	Custom field type.
`customFields[].value`	no	yes	string/number/boolean	yes	Stored value.
`customFields[].updatedAt`	no	yes	string	yes	Field update timestamp.

Create a client

POST /public/v1/clients
Authorization: Bearer <access_token>
Content-Type: application/json

Required scope:

clients:write

{
  "firstName": "Jane",
  "lastName": "Doe",
  "email": "jane@example.com",
  "assignedCoach": "66f7b8b1e13c8d25f4d3d90a",
  "tags": ["66f7b8b1e13c8d25f4d3d90b"],
  "inviteByEmail": true
}

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:

Field	Type	Required	Rule
`firstName`	string	yes	Trimmed length must be at least 2 and at most 50 characters.
`lastName`	string	no	Maximum 50 characters when supplied.
`email`	string	conditional	Required unless `hasNoEmail=true`; normalized and validated as an email address.
`hasNoEmail`	boolean/string	no	When true, FITsociety generates a placeholder email and `email` is ignored.
`assignedCoach`	ObjectId string	conditional	Defaults to the OAuth client’s `defaultAssignedCoachId`; must reference an active coach in the authenticated company.
`language`	string	no	Defaults to the company primary language, then `nl`.
`timeZone`	string	no	Defaults to `Europe/Amsterdam`.
`tags[]`	ObjectId string[]	no	All tags must exist in the authenticated company and must not be deleted.
`inviteByEmail`	boolean/string	no	Sends a portal invite only when the client has a real email address.

New-client responses return:

Field	Type	Nullable	Description
`data.client._id`	string	no	Created client ID.
`data.client.firstName`	string	no	First name.
`data.client.lastName`	string	no	Last name.
`data.client.email`	string	no	Email, empty for placeholder email accounts.
`data.client.emailIsPlaceholder`	boolean	no	Placeholder email flag.
`data.client.timeZone`	string	no	Stored IANA timezone.
`data.client.language`	string	no	Stored language code.
`data.companyClientData._id`	string	no	Company-client relation ID.
`data.companyClientData.assignedCoach`	string	no	Assigned coach ID.
`data.companyClientData.createdBy`	string	no	Coach ID used for creation attribution.
`data.companyClientData.tags[]`	string[]	no	Assigned company tag IDs.
`data.inviteSent`	boolean	no	Whether the invite email flow was triggered.

Existing-account responses return:

Field	Type	Nullable	Description
`data.clientId`	string	no	Existing client ID for which an approval request was sent.

If the existing client is already connected to the company, the endpoint returns 409 CLIENT_ALREADY_EXISTS_IN_COMPANY.

Update a client

PATCH /public/v1/clients/{clientId}
Authorization: Bearer <access_token>
Content-Type: application/json

Required scope:

clients:write

{
  "phoneNumber": "+31612345678",
  "assignedCoach": "66f7b8b1e13c8d25f4d3d90a",
  "assignTagIds": ["66f7b8b1e13c8d25f4d3d90b"]
}

Supported update fields:

Field	Notes
`firstName`, `lastName`, `email`	Basic profile fields
`phoneNumber`, `phoneCode`, `gender`, `dateOfBirth`	Contact/profile fields
`language`, `timeZone`, `height`, `profession`, `companyName`	CRM profile fields
`location`	Object with `addressLine1`, `addressLine2`, `zipCode`, `city`, `country`
`assignedCoach` or `coachId`	Assigns the client to a coach
`tagIds`	Replaces all assigned tag IDs
`assignTagIds`, `removeTagIds`	Adds or removes tag IDs incrementally

Archive a client

POST /public/v1/clients/{clientId}/archive
Authorization: Bearer <access_token>
Content-Type: application/json

Required scope:

clients:write

{
  "reason": "Duplicate profile"
}

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:

Field	Type	Nullable	Description
`data.lifecycle.clientId`	string	no	Client ID.
`data.lifecycle.relationshipStatus`	string	no	Lifecycle relationship status.
`data.lifecycle.memberStatus`	string	no	Member status.
`data.lifecycle.portalAccessStatus`	string	no	Portal access status.
`data.lifecycle.archivedAt`	string	yes	Archive timestamp.
`data.lifecycle.archiveReason`	string	no	Public archive reason, capped at 500 characters.

Validation:

Input	Rule
`clientId`	Must be a valid client ID connected to the authenticated company.
`reason` or `archiveReason`	Optional string, trimmed and capped at 500 characters.

The response does not expose archivedBy, removal outcomes, deletion flags, or internal retention fields.

Portal access and onboarding

GET  /public/v1/clients/{clientId}/portal-access
POST /public/v1/clients/{clientId}/invite
POST /public/v1/clients/{clientId}/invite/resend
POST /public/v1/clients/{clientId}/relationship/approve
POST /public/v1/clients/{clientId}/relationship/reject

Required scopes: clients:read for portal-access, client_onboarding:write for invite and relationship decisions. 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:

Field	Type	Nullable	Description
`data.portalAccess.clientId`	string	no	Client ID.
`data.portalAccess.relationshipStatus`	string	no	Company relationship status.
`data.portalAccess.memberStatus`	string	no	Company member status.
`data.portalAccess.portalAccessStatus`	string	no	Portal access status.
`data.portalAccess.invitationStatus`	string	yes	Invitation status when stored.
`data.portalAccess.emailIsPlaceholder`	boolean	no	Placeholder email flag.
`data.portalAccess.pendingApproval`	boolean	no	Whether the relationship is waiting for approval.
`data.portalAccess.reviewedAt`	string	yes	Registration review timestamp when stored.

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 use the existing coach invite flow and return:

Field	Type	Nullable	Description
`data.invite.clientId`	string	no	Client ID.
`data.invite.inviteSent`	boolean	no	Whether the invite flow accepted the request.
`data.invite.sentAt`	string	no	Invite request timestamp.
`data.portalAccess.clientId`	string	no	Client ID.
`data.portalAccess.relationshipStatus`	string	no	Company relationship status.
`data.portalAccess.memberStatus`	string	no	Company member status.
`data.portalAccess.portalAccessStatus`	string	no	Portal access status.
`data.portalAccess.invitationStatus`	string	yes	Invitation status when stored.
`data.portalAccess.emailIsPlaceholder`	boolean	no	Placeholder email flag.
`data.portalAccess.pendingApproval`	boolean	no	Whether the relationship is waiting for approval.
`data.portalAccess.reviewedAt`	string	yes	Registration review timestamp when stored.

Relationship decision endpoints are for clients whose company relation is pending_approval. Approve request body:

Field	Type	Required	Rule
`reviewMessage`	string	no	Optional review message, capped at 1000 characters.
`reason`	string	no	Optional reason, capped at 1000 characters.

Reject request body:

Field	Type	Required	Rule
`reason`	string	no	Optional rejection reason, max 500 characters.

Relationship decision response fields:

Field	Type	Nullable	Description
`data.clientRegistrationRequest.clientRegistrationRequestId`	string	no	Registration request ID when available.
`data.clientRegistrationRequest.clientId`	string	no	Client ID.
`data.clientRegistrationRequest.status`	string	no	`approved` or `rejected`.
`data.clientRegistrationRequest.relationshipStatus`	string	no	Updated relationship status.
`data.clientRegistrationRequest.memberStatus`	string	no	Updated member status.
`data.clientRegistrationRequest.requestedAt`	string	yes	Original request timestamp.
`data.clientRegistrationRequest.reviewedAt`	string	yes	Decision timestamp.
`data.clientRegistrationRequest.reviewMessage`	string	no	Public review message.

Not exposed: reviewed-by coach ID, raw approval helper payloads, auth tokens, password state, registration source internals, private notes, or deletion metadata.

Custom field definitions

GET /public/v1/client-custom-fields
Authorization: Bearer <access_token>

Required scope:

client_custom_fields:read

Returns active custom fields that are visible on the client page. Hidden fields, inactive fields, usage flags, internal update metadata, and validation regex patterns are not exposed. Definition fields:

Field	Type	Nullable	Description
`data.customFields[].key`	string	no	Stable custom field key.
`data.customFields[].label.en`	string	no	English label.
`data.customFields[].label.nl`	string	no	Dutch label.
`data.customFields[].type`	string	no	`text`, `textarea`, `number`, `date`, `select`, or `checkbox`.
`data.customFields[].mode`	string	no	`optional` or `required`.
`data.customFields[].order`	number	no	Display order.
`data.customFields[].placeholder.en`	string	no	English placeholder.
`data.customFields[].placeholder.nl`	string	no	Dutch placeholder.
`data.customFields[].helpText.en`	string	no	English help text.
`data.customFields[].helpText.nl`	string	no	Dutch help text.
`data.customFields[].validation.minLength`	number	yes	Minimum text length.
`data.customFields[].validation.maxLength`	number	yes	Maximum text length.
`data.customFields[].validation.min`	number	yes	Minimum numeric value.
`data.customFields[].validation.max`	number	yes	Maximum numeric value.
`data.customFields[].options[].value`	string	no	Select option value.
`data.customFields[].options[].label.en`	string	no	English option label.
`data.customFields[].options[].label.nl`	string	no	Dutch option label.
`data.customFields[].options[].order`	number	no	Option order.

Client custom field values

GET /public/v1/clients/{clientId}/custom-fields
PATCH /public/v1/clients/{clientId}/custom-fields

Required scopes: client_custom_fields:read for reads, client_custom_fields:write for writes. Patch body:

{
  "customFieldValues": [
    { "key": "shirt_size", "value": "m" }
  ]
}

Value response fields:

Field	Type	Nullable	Description
`data.clientId`	string	no	Client ID.
`data.customFields[].key`	string	no	Custom field key.
`data.customFields[].label.en`	string	no	English label snapshot.
`data.customFields[].label.nl`	string	no	Dutch label snapshot.
`data.customFields[].type`	string	no	Field type.
`data.customFields[].value`	string/number/boolean	yes	Stored scalar value. Non-scalar values are JSON encoded strings.
`data.customFields[].updatedAt`	string	yes	Value update timestamp.

Validation:

Input	Rule
`clientId`	Must be connected to the authenticated company.
`customFieldValues` or `customFields`	Required array.
`customFieldValues[].key`	Must match a configured, active, client-page custom field.
`customFieldValues[].value`	Validated against the stored field type, select options, required mode, and min/max constraints.

Assigned coaches

GET /public/v1/clients/{clientId}/assigned-coaches
PATCH /public/v1/clients/{clientId}/assigned-coaches

Required scopes: clients:read for reads, clients:write for writes. Patch body:

{
  "coachId": "66f7b8b1e13c8d25f4d3d90a"
}

Set coachId to null or an empty value to clear the assignment. Response fields:

Field	Type	Nullable	Description
`data.clientId`	string	no	Client ID.
`data.primaryCoach.coachId`	string	yes	Assigned coach ID.
`data.primaryCoach.name`	string	yes	Assigned coach name.
`data.primaryCoach.imageUrl`	string	no	Coach image URL when configured.
`data.assignedCoaches[]`	array	no	Array containing the current primary coach when assigned.
`data.assignedCoaches[].coachId`	string	no	Assigned coach ID.
`data.assignedCoaches[].name`	string	no	Assigned coach name.
`data.assignedCoaches[].imageUrl`	string	no	Coach image URL when configured.

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

GET /public/v1/clients/{clientId}/timeline?page=1&limit=50
Authorization: Bearer <access_token>

Required scope:

client_timeline:read

Timeline is intentionally limited to sanitized lifecycle events. It excludes notes, provider payloads, workout/nutrition events, raw audit logs, payment provider data, deletion internals, and retention details. Response fields:

Field	Type	Nullable	Description
`data.page`	integer	no	Current page.
`data.limit`	integer	no	Page size after cap, default `50`, maximum `100`.
`data.total`	integer	no	Total timeline events.
`data.totalPages`	integer	no	Total page count.
`data.hasNextPage`	boolean	no	Whether a next page exists.
`data.hasPrevPage`	boolean	no	Whether a previous page exists.
`data.timeline[].type`	string	no	Event type, such as `client_created`, `relationship_started`, `archived`, or `reactivated`.
`data.timeline[].occurredAt`	string	yes	Event timestamp.
`data.timeline[].title`	string	no	Human-readable title.
`data.timeline[].description`	string	no	Public description when configured.

Validation:

Input	Rule
`clientId`	Must be connected to the authenticated company.
`page`	Integer, minimum `1`.
`limit`	Integer, default `50`, maximum `100`.

DELETE /public/v1/clients/{clientId} is not exposed in v1. Client removal touches identity, memberships, payments, appointments, and connected company state, so it needs an explicit archive/removal contract rather than generic CRUD delete semantics.

Client tags

GET /public/v1/client-tags
Authorization: Bearer <access_token>

Required scope:

clients:read

Use this endpoint to fetch tag IDs before creating or updating clients. Response fields:

Field	Type	Nullable	Description
`data.data[].tagId`	string	no	Company tag ID.
`data.data[].name`	string	no	Tag name.
`data.data[].color`	string	no	Tag color.
`data.data[].totalClients`	integer	no	Number of visible company-client relations currently using this tag.

Deleted tags, hidden relationship statuses, and removed client outcomes are not included in the counts.

Start here

Public API guides

Access Devices

List clients

Get a client

Client output fields

Create a client

Update a client

Archive a client

Portal access and onboarding

Custom field definitions

Client custom field values

Assigned coaches

Client timeline

Client tags

​List clients

​Get a client

​Client output fields

​Create a client

​Update a client

​Archive a client

​Portal access and onboarding

​Custom field definitions

​Client custom field values

​Assigned coaches

​Client timeline

​Client tags

List clients

Get a client

Client output fields

Create a client

Update a client

Archive a client

Portal access and onboarding

Custom field definitions

Client custom field values

Assigned coaches

Client timeline

Client tags