Skip to main content
An external reference is an opaque ID from your system. Its namespace consists of the authenticated company, the stable OAuth client ID and the resource type. The same ID can exist in another company, another integration or another resource type. Rotating a client secret preserves this namespace. Creating a replacement OAuth client creates a separate namespace; it does not transfer references. References have no 24-hour expiry. Durable unique indexes allow at most one resource per external ID and one external ID per resource in each namespace. The server derives ownership from the verified OAuth token. Callers cannot set company IDs, source IDs or internal import metadata to claim another namespace.

​
Bind or edit an existing client

First find the client through the company-scoped client resources. Use this operation to bind a client that is already linked to your company:
This requires clients:write. externalId must be a nonblank string of at most 200 characters without control characters; surrounding whitespace is trimmed. The first binding requires revision: 1. Revisions must be JSON integers from 1 through 9007199254740991. To edit the ID, send the same client path with a strictly greater revision and a new idempotency key for that logical update:
An identical externalId and revision replays successfully. A stale revision, a different ID with the same revision, or an ID already bound to another client returns 409. The binding’s client cannot be changed by this operation. Editing replaces the old ID, so update your local register and stop retrying creation or lookup with the old ID. This operation does not change app access, modify the global client profile or take over a manually managed relationship.

​
Read and look up your reference

These reads require clients:read:
The dedicated read returns data.externalReference, or null if your source has no binding. Client detail and list items expose the same optional object:
The exact externalId filter applies before counting and pagination and combines with the existing email, search and status filters. Other integrations’ IDs never appear in your output or match this filter. Company relationship visibility continues to apply; a reference does not grant access to an unavailable client.

​
Durably deduplicate creation

Pass an optional string externalReference to the existing create resource. Creation chooses initial revision 1; the explicit client binding operation uses the {externalId, revision} object instead.
The normal assigned-coach configuration and create validation still apply. An existing global account can be linked to a new company relationship without changing its profile. For a client already linked to your company, use the explicit reference PUT above. Referenced creation also supports these Workout V2 resources with their existing write scopes, required fields, consent checks and company resource checks:
  • POST /public/v1/workout/exercises
  • POST /public/v1/workout/clients/{clientId}/exercises
  • POST /public/v1/workout/plans
  • POST /public/v1/workout/plans/create-and-assign/{clientId}
Referenced workout creation accepts application/json only. Multipart requests and uploaded files are rejected; use the ordinary media workflow separately. The external reference does not relax exercise classification or programme validation. See the API reference for complete programme, day, set, superset, rest, tempo and calendar definitions. The resource and reference commit in one MongoDB transaction. A failed mapping cannot leave an orphan client, exercise or plan. Client mails, webhooks and default measurement assignment start only after commit. An opted-in OAuth client also persists the new relationship’s required external app-access policy inside that transaction; see External client access. An identical create request with the same external reference returns the same resource, including after the HTTP idempotency record expires. Changed creation content or reuse through a different endpoint or client path returns 409. Object-key order does not matter; array order and supplied field values do. A replay does not recreate assignments, reset workout performance or send another invitation. Use the normal read endpoint when you need the resource’s current profile or plan state after later edits. Successful referenced creates add this receipt alongside the existing resource ID in data:
Every write still requires an Idempotency-Key. Keep the same key when retrying one HTTP operation; after its retention window, the durable reference remains the resource-level recovery mechanism. Keep your own step register for client, exercise, plan, assignment and access-entitlement synchronization. Resource creation alone does not confirm that app or client-AI access is effective.