Skip to content
Uptivo Developers

Badge awards

Use badge award reads to import existing awards, show an Athlete’s achievement history, or recover missed Badge.Awarded events. All three operations are read-only and require Read or ReadWrite access.

Choose an operation

Section titled “Choose an operation”
Need API reference
List awards visible to the selected club GET /BadgeAwards
List one Athlete’s awards GET /Athletes/{userId}/BadgeAwards
Read one award GET /BadgeAwards/{achievedBadgeId}

Understand award visibility

Section titled “Understand award visibility”

These operations return challenge awards belonging to current Athletes of the selected club. The award must come from a challenge associated with that club or its brand; ownership of the badge design does not determine visibility. They do not return all of an Athlete’s badges from unrelated clubs or brands.

If an Athlete leaves the club, their awards are no longer available through these operations. A detail read returns 404 Not Found for an absent or inaccessible award. The Athlete-specific list also returns 404 when the User is not a current Athlete; an eligible Athlete with no awards receives an empty page.

Identify an award

Section titled “Identify an award”

Every operation returns ClubBadgeAwardDTO. The following is a partial, illustrative response:

{
  "Id": "badge-920001",
  "AchievedBadgeId": 920001,
  "UserId": 300001,
  "BadgeId": 910001,
  "BadgeName": "First milestone",
  "PictureUri": "https://cdn.example.test/badges/first-milestone.png",
  "AchievedAt": "2026-09-15T18:00:00Z",
  "ChallengeName": "September activity challenge",
  "ClubId": 100001,
  "BrandId": null,
  "GoalStep": 0
}

Use AchievedBadgeId for detail reads and idempotent storage. BadgeId identifies the design, not the award: earning the same badge again creates a different AchievedBadgeId. Id is the equivalent string badge-<award-id>; it is not the webhook envelope’s event ID.

AchievedAt is the effective award date, which can precede assignment. Lists are ordered by award ID, not this timestamp. ClubId and BrandId describe the challenge’s scope, not necessarily the receiving club.

Challenge, goal, and ranking context can be null. GoalStep, when provided, is zero-based. Ranking context uses Rank, RankPercent, Score, RankingCriteria, and Participants. Consult the API reference for the full schema rather than assuming that every award includes those values.

Import and paginate history

Section titled “Import and paginate history”

Both lists default to 100 items and accept count from 1 to 1,000. Without ID bounds they return the latest award IDs first. To import all visible history in ascending ID order, start with fromId=1:

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

Repeat the original parameters and pass the returned NextCursor unchanged:

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

fromId and toId are inclusive award-ID bounds. fromId selects ascending order; toId alone selects descending order. NextCursor moves toward larger award IDs and PrevCursor toward smaller ones. For the default newest-first view, use PrevCursor to continue into older awards.

There is no date filter on these lists. Import by ID and apply any display-date filter locally. See Pagination and synchronization for complete loops, checkpoints, and retries.

Combine history with webhooks

Section titled “Combine history with webhooks”

Use Badge.Awarded for prompt award notifications and the history endpoints for initial imports and reconciliation. Deduplicate business records by AchievedBadgeId, including when a read and an event describe the same award.

The event and read response are not identical. TrainingChallengeId and AwardType are available in the event but not in ClubBadgeAwardDTO. Retain the event payload if your integration needs them; fetching the award is not a way to reconstruct the entire event.

GET /Athletes/{userId}/EngagementSummary includes awards in the Athlete’s current local month, not complete award history. Use the dedicated award list when you need older awards, and preserve previously received events according to your retention policy.