Athletes

An athlete is the relationship between an Uptivo user and the club selected by the Club API Key. The UserId identifies the person across athlete, training, subscription, and class-participation responses.

Before changing athletes, call GET /Profile and verify the selected club as described in the Club guide.

Choose an operation

Need	API reference
List athletes	`GET /Athletes`
Add, create, or invite an athlete	`POST /Athletes`
Read one athlete	`GET /Athletes/{userId}`
Read current-month and lifetime engagement	`GET /Athletes/{userId}/EngagementSummary`
Read engagement for all current athletes	`GET /Athletes/EngagementSummaries`
Read one Athlete’s effective membership	`GET /Athletes/{userId}/MembershipSummary`
Read membership for all current athletes	`GET /Athletes/MembershipSummaries`
Read one Athlete’s attendance	`GET /Athletes/{userId}/AttendanceSummary`
Read attendance for all current athletes	`GET /Athletes/AttendanceSummaries`
Read an Athlete’s challenge badge history	`GET /Athletes/{userId}/BadgeAwards`
Partially update an athlete	`PUT /Athletes/{userId}`
Set the club commercial stage	`PUT /Athletes/{userId}/ClientStage`
Set the club guest flag	`PUT /Athletes/{userId}/IsGuest`
Remove an athlete from the club	`DELETE /Athletes/{userId}`

Read athletes

Use GET /Athletes for an initial import or reconciliation:

curl --request GET \
  --url "https://api-gw.uptivo.fit/club/Athletes?fromId=1&count=500" \
  --header "X-Sub-Key: <subscription-key>" \
  --header "Authorization: Bearer <club-api-key>"

The default page size is 500 and the maximum is 1,000. Repeat all parameters from the first request and pass each returned NextCursor unchanged through cursor:

GET /Athletes?fromId=1&count=500&cursor=<NextCursor>

See Pagination and synchronization for the complete loop, reverse traversal, migration from range pagination, and reconciliation strategy.

To read one athlete, use its UserId:

curl --request GET \
  --url https://api-gw.uptivo.fit/club/Athletes/300001 \
  --header "X-Sub-Key: <subscription-key>" \
  --header "Authorization: Bearer <club-api-key>"

The API returns 404 Not Found both when the user does not exist and when the user is not an athlete of the selected club. This prevents resource IDs from revealing data across club boundaries.

Read engagement results

GET /Athletes/{userId}/EngagementSummary returns the athlete’s current local month and lifetime activity totals, awards earned so far in that month, and current Uptivo and selected-brand levels. The totals cover the athlete’s activity across clubs, not only activity in the selected club. CurrentYear and CurrentMonth identify the athlete-local month; this operation does not accept a historical period. Missing activity aggregates appear as zero totals. The endpoint returns 404 when the athlete is absent or outside the selected club.

For a workout’s creation-time totals, use the Training.Created event. Its TrainingMonthTotals refer to that workout’s local month, which need not be the athlete’s current month.

Use GET /Athletes/EngagementSummaries to retrieve the same representation for every current, non-demo Athlete. The paginated result includes Athletes with zero totals. CurrentLevel, MonthToDatePoints, MonthlyPointsGoal, and MonthlyPointsResetAtUtc provide the effective level and current-month goal progress. BrandLevelSource identifies which activity source is used. For field semantics and bulk engagement, membership, attendance, and booking reads, see Bulk summaries and bookings.

Read membership and badge history

GET /Athletes/{userId}/MembershipSummary combines all of the Athlete’s club UserSubscriptions into an effective Status, with the assignment details in Memberships. Use it rather than inferring membership from one assignment. For state precedence and reconciliation, see Read effective membership states.

GET /Athletes/{userId}/BadgeAwards reads visible club or brand challenge awards across the Athlete’s history, unlike the current-month awards in the engagement summary. See Badge awards for visibility, pagination, and webhook reconciliation.

Add an athlete

POST /Athletes uses the email address to choose one of two workflows:

if the email does not belong to an Uptivo user, the API creates the user and immediately makes that user an athlete of the club;
if the email belongs to an Uptivo user who is not in the club, the API sends an invitation by default. Set UserConfirmed to true only when the club has already obtained the user’s consent through another valid process; the existing user is then added immediately.

A conservative request lets Uptivo perform the normal onboarding flow:

curl --request POST \
  --url https://api-gw.uptivo.fit/club/Athletes \
  --header "Content-Type: application/json" \
  --header "X-Sub-Key: <subscription-key>" \
  --header "Authorization: Bearer <club-api-key>" \
  --data '{
    "Email": "alex@example.test",
    "FirstMidName": "Alex",
    "LastName": "Example",
    "BirthDate": "1990-06-15",
    "Gender": "Unspecified",
    "Weight": 70,
    "Height": 180
  }'

Weight is expressed in kilograms and Height in centimeters, independently of the club’s display settings. Consult the ClubAthleteCreateDTO schema in the POST /Athletes reference for validation limits and optional fields.

Successful outcomes

A 200 OK response contains ClubAthleteCreateResultDTO. Inspect Result to learn which successful workflow occurred:

`Result`	Meaning	Recommended action
`Created`	A new Uptivo user was created and added as an athlete.	Persist the returned `User.UserId`.
`Added`	An existing Uptivo user was immediately added because `UserConfirmed` was `true`.	Persist the returned `User.UserId`.
`Invited`	An existing user was invited and has not joined yet.	Store the returned ID as a pending link; wait for acceptance or reconcile later.
`AlreadyInClub`	The account is already an athlete of the selected club. `EmailVerified` and `Sensors` are still applied when supplied.	Use the returned athlete data. Repeating the same sensor import does not create duplicates.
`PendingInvitation`	An invitation for that email already exists.	Do not create another invitation; wait or reconcile later.

The User property is not guaranteed for every outcome. The Invited and PendingInvitation responses contain only identification data, not a complete athlete profile.

Failed outcomes

Failed workflows use the appropriate HTTP status and an ApiErrorDTO body:

Status	`ErrorType`	Meaning and action
`400 Bad Request`	`InvalidData`	Account creation rejected the supplied data. Correct the request; do not retry it unchanged.
`403 Forbidden`	`LicenseResourceLimitExceeded`	The club license cannot accept another athlete. Stop and ask the club to resolve its license capacity.
`409 Conflict`	`EmailAlreadyInUse`	The email became unavailable during account creation, commonly because it was registered concurrently. Reconcile the user’s current state before deciding whether to retry.
`500 Internal Server Error`	`Internal`	The workflow could not be completed. Do not assume the athlete is absent; reconcile before a controlled retry.

The application-level errors above use ApiErrorDTO. A request rejected by request-body validation can instead contain field validation details. An authorization or inactive-license 403 may have no response body; the LicenseResourceLimitExceeded body specifically identifies exhausted athlete capacity. Never branch on the human-readable Message.

Account and import options

These options should be enabled deliberately:

Property	Behavior
`UserConfirmed`	Adds an existing Uptivo user immediately instead of inviting them. The club must have obtained consent through another process.
`EmailVerified`	Declares that the email address has already been verified. It applies to both new and existing users when `true`; `false` never removes an existing verification. Set it only when your integration has a trustworthy verification process.
`ShowPasswordOnCreate`	Returns the generated password in `Password` when a new user is created. Avoid this unless the integration can handle plaintext credentials securely.
`SetPasswordOnCreate`	Sets a password of 6–16 characters for a newly created user. Never log or persist it in plaintext.
`NoEmailOnCreate`	Suppresses the account-creation email. The new user must use password recovery unless another approved onboarding flow supplies access.
`UptivoLevel`	Sets the starting Uptivo level for a newly created user. Leave `0` for the default.
`Sensors`	Associates Uptivo, Garmin, or MyZone sensors with a new or existing user. Each item contains `SensorBrand` and `SensorSN`. Existing sensors are preserved, and importing a sensor already associated with the same user does not create a duplicate.

When the email already belongs to an Uptivo user, UserConfirmed, EmailVerified, and Sensors retain the behavior described above. Profile values and the remaining account-creation options are ignored so that this operation cannot overwrite the shared Uptivo user profile. Prefer the default false values unless Uptivo has approved the corresponding onboarding flow.

Update an athlete

PUT /Athletes/{userId} applies only the non-null fields supplied in the request. Every property is optional, so send only the values that must change:

curl --request PUT \
  --url https://api-gw.uptivo.fit/club/Athletes/300001 \
  --header "Content-Type: application/json" \
  --header "X-Sub-Key: <subscription-key>" \
  --header "Authorization: Bearer <club-api-key>" \
  --data '{
    "Phone": "+390200000001"
  }'

Omitted fields remain unchanged. The response is the updated athlete; sending no changed value is also successful and returns the current athlete.

The endpoint returns 409 Conflict if the requested email is already used:

{
  "ErrorType": "EmailAlreadyInUse",
  "Message": "Email address is already in use"
}

An update returns 403 Forbidden when the account also has a trainer or manager role. It returns 404 Not Found when the athlete is absent or outside the selected club.

Update club-specific state

Use the dedicated operations for ClientStage and IsGuest. Unlike the profile update above, these change only the Athlete relationship in the selected club. They do not change the shared Uptivo user profile or the person’s relationships in other clubs.

curl --request PUT \
  --url https://api-gw.uptivo.fit/club/Athletes/300001/ClientStage \
  --header "Content-Type: application/json" \
  --header "X-Sub-Key: <subscription-key>" \
  --header "Authorization: Bearer <club-api-key>" \
  --data '{"ClientStage":"Qualified"}'

ClientStage must be one of Lead, Qualified, Prospect, or Client. When an Athlete first reaches Qualified, Prospect, or Client, the corresponding UTC milestone is recorded. Later stage changes do not erase earlier milestones.

curl --request PUT \
  --url https://api-gw.uptivo.fit/club/Athletes/300001/IsGuest \
  --header "Content-Type: application/json" \
  --header "X-Sub-Key: <subscription-key>" \
  --header "Authorization: Bearer <club-api-key>" \
  --data '{"IsGuest":false}'

IsGuest must be an explicit JSON Boolean. Both operations return the updated ClubAthleteDTO with 200 OK. Repeating the current value succeeds without publishing another event. A missing or invalid body returns 400; an absent, out-of-club, or demo Athlete returns 404. These writes require ReadWrite access and return 403 for an inactive license or insufficient permission. Real changes publish Athlete.Updated.

Guest Athletes are excluded from the selected club’s ranking athlete set. Clearing the guest flag does not override the other ranking eligibility settings.

Remove an athlete from the club

curl --request DELETE \
  --url https://api-gw.uptivo.fit/club/Athletes/300001 \
  --header "X-Sub-Key: <subscription-key>" \
  --header "Authorization: Bearer <club-api-key>"

This removes only the athlete relationship with the selected club. It does not delete the global Uptivo user, their membership in other clubs, or any trainer or manager role they may have. The response contains the athlete snapshot captured before removal.

Deletion returns 403 Forbidden for a demo athlete or when the license/key permissions do not allow the operation. It returns 404 Not Found when the athlete is absent or belongs to another club.

Permissions and events

Reads require a Club API Key with Read or ReadWrite access. Creating, updating, and removing athletes require ReadWrite access. A missing or invalid credential returns 401; an inactive Club API license or insufficient key permission returns 403.

Completed athlete creation, update, and removal operations produce athlete webhook events. Invitations do not represent a completed athlete relationship; combine webhooks with periodic reconciliation as described in the receiving events guide.