Skip to main content
The clients module provides tools to search, retrieve, create/link, and inspect client profile access within the company scope.

Available Tools

Home branches

list_client_home_locations lists eligible company home branches within your current staff location scope. Optional query searches names; page starts at 1 and limit defaults to 25 (maximum 100). The result contains locations with stable locationId and name, plus page, limit, total and hasMore. get_client_home_location accepts clientId and returns the current assignment with hasHomeLocation, homeLocationId and homeLocation (locationId, name). An unset assignment has hasHomeLocation: false; empty optional fields may be omitted from compact responses. update_client_home_location requires clientId, homeLocationId (an eligible branch ID, or explicit null to clear it), a nonblank reason of 3–500 characters, userConfirmed: true and an idempotency key. Review the target member and branch with the user before confirming. The result includes changed and hasHomeLocation. Only the home branch changes. The member’s postal address, signup location, coach, lifecycle and bookings are separate. Reads require current members.view permission; updates require members.update, access to the member and destination branch, and the explicit update_client_home_location write grant. These checks also apply to retries. Branches must belong to the connected company and be eligible for member assignment. Archived or unavailable branches cannot be assigned. For multiple members, use the optional customer imports module.

Member status automation and history

get_member_status_automation reads the effective company rules. It returns rules as an array of { event, action } and preserveManualStatuses. The seven events, all allowed actions and company defaults are documented in company status automation. update_member_status_automation accepts a partial statusAutomation object and/or a boolean preserveManualStatuses. Omitted rules and other settings are preserved. It returns the effective rules array and protection flag. Changes apply to future lifecycle events without updating existing members in bulk. An explicit grant for this write tool and an idempotency key are required. The connection’s owner must also retain active company access and access.settings.update; standard authorization mode requires an Admin. The tool grant does not replace this company permission check. update_client_lifecycle requires clientId plus at least one of relationshipStatus (trial, active, paused, inactive), portalAccessStatus (enabled, disabled, suspended) or relationshipStatusMode (automatic, manual). A status edit defaults to manual protection; automatic mode resumes company rules for future events. It returns a lifecycle object with client ID, relationship status, mode, member status and portal access. Protected relationship states require their dedicated workflows. Existing client access rules apply. An explicit grant for this tool and an idempotency key are required. list_client_status_history requires clientId and accepts page (default 1) and limit (default 50, maximum 100). It returns current relationshipStatus and relationshipStatusMode, pagination metadata, and history ordered newest first. Entries contain fromStatus, toStatus, source (automatic, coach, integration, system), event, UTC changedAt and nullable changedByCoachId. Mode changes may retain the same status. Earlier changes may have no recorded history. Client search and detail also return relationship.statusMode.

search_clients

Search the company’s client list by name or email, optionally filtered by tag or home location. Returns paginated client summaries including relationship.tags and relationship.homeLocation.
  • Type: Read-only
  • Important Input Fields:
    • query (string, optional): Search string matched against first name, last name, or email. Max 200 chars.
    • relationshipStatus (string, optional): Filter by status (e.g. active, invited, inactive).
    • tag (string, optional): Tag name, exact and case-insensitive (e.g. testaccount).
    • homeLocationId (string, optional): Only clients with this home location.
    • page (integer, optional): Page number, starting at 1.
    • limit (integer, optional): Page size, max 50.

get_client

Retrieve a client’s complete profile, including tags and home location. relationship.homeLocation is the company location the member belongs to; location is the member’s postal address. followUp contains the follow-up date, its source (manual, retention or unknown) and the assignedCoach, or null values when no follow-up is set.
  • Type: Read-only
  • Important Input Fields:
    • clientId (string, required): Unique client identifier.

create_client Write

Create a new client profile or link an existing account by email to the company.
  • Type: Write
  • Important Input Fields:
    • firstName (string, required): Client first name. Min 2 chars.
    • email (string, required): Client email.
    • lastName (string, optional): Client last name.
    • inviteByEmail (boolean, optional): Whether to send invite email.
    • homeLocationId (string or null, optional): Eligible company home branch. Omitting it preserves the existing create/link behavior. Supplying it also requires current members.create permission and member/location scope. An existing company relationship must be readable; use the dedicated relationship workflow for a rejected or removed relationship first.

inspect_client_data_access

Inspect stored external-data grants and company connection status for a client. External-data grants are reserved for separately authorized sources such as future wearable integrations. An empty list does not block company-owned nutrition or measurements and is separate from the connection’s health consent.
  • Type: Read-only
  • Important Input Fields:
    • clientId (string, required): Unique client identifier.

get_retention_planner_rules

Retrieve the retention planner rules: conditions, suppression settings and configured actions (follow-up, todo, coach notification, member email, member chat). Email and chat bodies are not returned. Returns the default rules with isDefault: true when the company has not saved settings.
  • Type: Read-only
  • Important Input Fields:
    • enabledOnly (boolean, optional): Only return enabled rules.

list_retention_members

List members who currently match the retention planner rules (risk list), read from the precomputed retention projection. Returns matched rules with severity and priority, follow-up date and cheap activity counters. Member emails are not returned. freshness.status shows whether the projection is ready.
  • Type: Read-only, paginated
  • Important Input Fields:
    • ruleId (string, optional): Only members matching this rule.
    • severity (string, optional): watch, risk, highRisk or lost.
    • page, limit (integer, optional): Pagination (limit max 50).

list_retention_approvals

List retention outreach approvals (member emails and chats waiting for coach review), newest first. Only the email subject is returned, never the body.
  • Type: Read-only, paginated
  • Important Input Fields:
    • status (string, optional): pending (default), sent, rejected, failed, skipped or all.
    • ruleId (string, optional): Only approvals from this rule.
    • page, limit (integer, optional): Pagination (limit max 50).

list_client_field_catalog

List the company’s member tags (with member counts) and the active custom client field definitions (key, label, type, required, select options).
  • Type: Read-only
  • Important Input Fields: none.

update_client_custom_field_values

Update one or more values on an existing member using clientId and customFieldValues: [{ key, value }]. Requires a separate write grant and an idempotencyKey. Only existing, active, non-hidden fields enabled for the client page can be changed. Values are validated against the field type, configured options and validation rules. Automatic numbering fields are read-only. Other values are preserved; null or an empty string clears a value. For a newsletter opt-out checkbox, use its existing field key with the boolean value true (the displayed label may be “Yes”). The tool changes the member field; it does not unsubscribe the member in an external mailing system.
The response contains clientId and updatedKeys. Unknown or non-writable fields and invalid values fail validation. Use list_client_field_catalog to find existing definitions and get_client to read the resulting member values.

update_client_tags

Add or remove existing company tags for one accessible member. Requires the clients module, its own update_client_tags write grant, current member update permission and an idempotencyKey. This tool is available to company/coach connections. It does not create tags.
  • clientId: Member ID.
  • assignTagIds and/or removeTagIds: At least one non-empty array of tag IDs, with at most 100 IDs per array. Get tag IDs from list_client_field_catalog.
  • idempotencyKey: Unique key for this change. Reuse it only for an exact retry.
Unspecified tags are preserved. Adding an assigned tag or removing an unassigned tag is a no-op. If an ID is in both lists, removal wins. Assigned tags must exist in the connected company and must not be deleted. Inaccessible members and unknown assigned tags fail without changing the member. Invalid IDs and empty updates are rejected. Access is checked again for retries. Reusing an idempotency key with different arguments returns a conflict.
The response contains clientId; read the resulting tags with get_client. Changes may emit a client.updated webhook. Normal MCP connection rate limits apply. Existing connections need explicit approval of the new write grant.

list_registration_requests

List member registration requests awaiting coach approval (or rejected), newest first, with signup location. Placeholder emails are returned as an empty string.
  • Type: Read-only, paginated
  • Important Input Fields:
    • status (string, optional): pending (default) or rejected.
    • page, limit (integer, optional): Pagination (limit max 50).

decide_registration_request Write

Approve or reject one pending member registration request from list_registration_requests, like the dashboard. Approve activates the member; reject declines the sign-up. reviewMessage is stored with the decision. Get explicit coach confirmation first.
  • Type: Write (requires userConfirmed: true and the write-tool grant)
  • Input Fields:
    • requestId (string, required)
    • decision (string: approve, reject, required)
    • reviewMessage (string, optional)
    • idempotencyKey (string, optional)

create_client_tag Write

Create a new company member tag (name and optional hex color like #1E88E5) that update_client_tags can then assign. Get explicit coach confirmation first.
  • Type: Write (requires userConfirmed: true and the write-tool grant)
  • Input Fields:
    • name (string, required)
    • color (string, optional)
    • idempotencyKey (string, optional)

list_client_custom_fields

List the full company shared member field library, including hidden and inactive definitions, labels, validation, usage and automatic numbering settings. Does not return member values. Page numbers start at 1; default limit 10, maximum 100.
  • Type: Read
  • Input Fields:
    • page (integer, optional)
    • limit (integer, optional)

create_client_custom_field Write

create one company shared member field definition. Keys cannot be renamed. Updates merge supplied properties and nested labels, usage and sequence settings. Deleting a used field hides and deactivates it while preserving all member values; unused fields are removed. Generated values remain read-only. Requires a separate explicit write grant and idempotency key.
  • Type: Write (requires userConfirmed: true and the write-tool grant)
  • Input Fields:
    • field (object, required)
    • idempotencyKey (string, optional)

update_client_custom_field Write

update one company shared member field definition. Keys cannot be renamed. Updates merge supplied properties and nested labels, usage and sequence settings. Deleting a used field hides and deactivates it while preserving all member values; unused fields are removed. Generated values remain read-only. Requires a separate explicit write grant and idempotency key.
  • Type: Write (requires userConfirmed: true and the write-tool grant)
  • Input Fields:
    • key (string, required)
    • field (object, required)
    • idempotencyKey (string, optional)

delete_client_custom_field Write

delete one company shared member field definition. Keys cannot be renamed. Updates merge supplied properties and nested labels, usage and sequence settings. Deleting a used field hides and deactivates it while preserving all member values; unused fields are removed. Generated values remain read-only. Requires a separate explicit write grant and idempotency key.
  • Type: Write (requires userConfirmed: true and the write-tool grant)
  • Input Fields:
    • key (string, required)
    • idempotencyKey (string, optional)

decide_retention_approval Write

Approve or reject one pending retention planner approval from list_retention_approvals. Approve runs the proposed action exactly as proposed (for example a member message or email); edit the proposal in the dashboard first if it must change. Reject needs a reason. An approval that is no longer pending returns status skipped. Show the coach the member and the exact action, and get explicit confirmation first.
  • Type: Write (requires userConfirmed: true and the write-tool grant)
  • Input Fields:
    • approvalId (string, required)
    • decision (string: approve, reject, required)
    • reason (string, optional)
    • idempotencyKey (string, optional)

Natural Language Examples

  • “Find Jane Doe in my company’s client list.”
  • “Create a new client named Tom Hardy with email tom.hardy@example.com.”
  • “Inspect the company connection and external-data grants for client 64b64c0f2f5f4c0012345678.”

JSON-RPC Call Example (search_clients)