Get User Challenges API - Track Progress & Gamification Goals

Retrieve user challenge progress, completion status, and available gamification tasks via our Challenges API. Perfect for building achievement systems, quest tracking, mission progress, and goal-based gamification features.

Supports onboarding challenges, recurring tasks, challenge series, and streak-based objectives. Ideal for loyalty programs, fitness apps, learning platforms, gaming applications, and any system using challenge-based engagement.

Retrieve all challenges for a specific user, including their progress, status, and completion state.

Endpoint

GET /user/{userId}/challenge

Path Parameters

Parameter	Type	Required	Description
`userId`	string	Yes	The unique identifier of the user

Query Parameters

Parameter	Type	Required	Description
`completed`	boolean	No	Filter challenges by completion status. `true` for completed, `false` for not completed

Response

Returns an object containing an array of challenges assigned to the user.

Response Schema

{
  "challenges": [
    {
      "index": 110,
      "event": "add_favourite_connection_v1",
      "challengeId": "Favori-iY6sx",
      "status": "ACTIVE",
      "createdAt": 1751366314965,
      "goal": 1,
      "image": "https://example.com/challenges/favorite-connection.jpg",
      "updatedAt": 1754660792785,
      "points": 15,
      "title": {
        "de": "Stammstrecke: Favorisiere eine Verbindung",
        "en": "Go-to route: favor a route connection",
        "default": "Stammstrecke: Favorisiere eine Verbindung"
      },
      "type": "FIXED",
      "progress": 0,
      "completed": false,
      "completedDate": null
    },
    {
      "index": 30,
      "event": "rent_bike_v1",
      "challengeId": "BikeSeries-JE3ew-tKXd1",
      "status": "ACTIVE",
      "createdAt": 1751360008114,
      "goal": 1,
      "isLastStep": false,
      "seriesId": "BikeSeries-JE3ew",
      "image": "https://example.com/challenges/bike-rental.png",
      "updatedAt": 1755002601255,
      "points": 5,
      "title": {
        "de": "Los geht's auf zwei Rädern: Leihe dein 1. Fahrrad",
        "en": "Off on two wheels: rent your 1st bike",
        "default": "Los geht's auf zwei Rädern: Leihe dein 1. Fahrrad"
      },
      "type": "FIXED",
      "progress": 0,
      "completed": false,
      "completedDate": null
    }
  ]
}

Field Descriptions

Challenge Object

Field	Type	Description
`index`	number	Sort order index for the challenge. Lower values (e.g., 10, 20) indicate priority challenges like onboarding tasks, while higher values represent standard challenges
`event`	string	The event type that triggers challenge progress
`challengeId`	string	Unique identifier for the challenge
`status`	string	Current status of the challenge (e.g., `ACTIVE`, `INACTIVE`)
`createdAt`	number	Unix timestamp when the challenge was created
`goal`	number	Target number of events required to complete the challenge
`image`	string	URL to the challenge image
`updatedAt`	number	Unix timestamp of the last update
`points`	number	Points awarded upon challenge completion
`title`	object	Localized challenge titles
`title.de`	string	German title
`title.en`	string	English title
`title.default`	string	Default/fallback title
`type`	string	Challenge type (e.g., `FIXED`)
`progress`	number	Current progress towards the goal
`completed`	boolean	Whether the challenge has been completed
`completedDate`	number \| null	Unix timestamp when completed, or `null` if not completed
`seriesId`	string	(Optional) ID of the challenge series this belongs to
`isLastStep`	boolean	(Optional) Whether this is the final challenge in a series
`streakTimeframe`	string	(Optional) Timeframe for streak challenges (`DAILY`, `WEEKLY`, `MONTHLY`)
`isChallengeStreak`	boolean	(Optional) Whether this is a streak-based challenge

Example Request

Get all challenges

curl -X GET "https://api.lynesapp.de/user/user123/challenge" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

Get only completed challenges

curl -X GET "https://api.lynesapp.de/user/user123/challenge?completed=true" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

Get only incomplete challenges

curl -X GET "https://api.lynesapp.de/user/user123/challenge?completed=false" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

Status Codes

Status Code	Description
`200`	Successfully retrieved user challenges
`401`	Unauthorized - Invalid or missing authentication token
`404`	User not found
`500`	Internal server error

💪 Challenges 🏆 Leaderboards