GET GetProgressChallengesInfoForUser

{baseurl}/api/v1/Integration/GetProgressChallengesInfoForUser?UserId={userId}

Overview

The GetProgressChallengesInfoForUser API endpoint retrieves a paginated list of challenges for a specific user, including progress details for each challenge.

The challenges can be filtered by category, searched by name, and ordered by specified criteria. The response also includes information about milestones, prizes, and group progress for the challenges.

Challenge Progress

Use Cases Examples:

1. Retrieve User-Specific Challenges with Progress:

   • This API can be used to get a list of all challenges that are available for a specific user, along with detailed progress information.

2. Filter Challenges by Category:

   • Users can filter challenges by a specific category using the CategoryId parameter.

3. Search Challenges with Progress by Name:

   • Users can search for challenges by their names using the SearchQuery parameter.

4. Paginate Results:

   • Large sets of challenges can be paginated using the Page and ItemsPerPage parameters.

5. Sort Challenges:

   • Challenges can be sorted by a specific field, either in ascending or descending order, using the OrderBy and IsAscending parameters.

---

Request

Header Parameters

Attribute	Type	Options	Description
X-ClientId	string	Required	Provided Client Id.
X-Message	string	Required	Provided encrypted message.
Accept-language	string	Optional	Selected language for response.

X-ClientId and X-Message are only required with V1 API.

Query Parameters

Property	Type	Options	Description
UserId	string	Required	The phone number of the user for whom challenges are being retrieved.
CategoryId	int	Optional	The ID of the category to filter challenges by.
Page	int	Optional	The page number of the results to retrieve. Default is 1.
ItemsPerPage	int	Optional	The number of items per page. Default is 10.
SearchQuery	string	Optional	A search string to filter challenges by name.
OrderBy	string	Optional	The field to order the results by. Default is Id.
IsAscending	bool	Optional	A flag indicating whether the results should be ordered in ascending order. Default is true.

Request Example

GET /api/v1/Integration/GetProgressChallengesInfoForUser?Page=1&ItemsPerPage=10&SearchQuery=badge&OrderBy=StartDate&IsAscending=true&UserId=12345&CategoryId=5

---

Response

Returns a challenge object if successful. Otherwise, return status Code message error.

Response Fields:

• data (List): A list of challenges.

• pagesNum (int): The current page number.

• count (int): The total number of challenges matching the criteria.

Response Parameters

Property	Type	Description
Id	int	Unique identifier for the challenge.
Name	string	The name of the challenge.
Description	string	Brief summary of the challenge.
Startdate	datetime	Challenge start date.
Enddate	datetime	Challenge end date.
PeopleFinished	int	Number of people that completed the challenge.
EndsAfter	int	Days left until the challenge ends.
IsLocked	bool	If isLocked equals 1 it waits until the parent challenge is achieved.
Visible	bool	Indicates whether the challenge is visible to the user or not.
Category*	object	Category info of the challenge.
Image	string	The URL for the challenge's image.
Prizes*	list	List of milestones that users have on that challenge.
GroupProgress*	list	An object that shows user progress over the triggers group.

Category: Category information of the challenge.

Property	Type	Description
Id	int	Unique identifier of the category.
Name	string	Name of the category.

Prizes (List of Milestones): The milestones won on the challenge.

Property	Type	Description
UserID	string	User phone number associated with the milestone.
MilestoneId	int	ID of the milestone associated with the prize
Prizes*	list	List of prize details, The prize appears only when it is not claimed, once claimed, it moves to history.

Prizes (List of Prizes): List of prize details

Property	Type	Description
Value	string	Value of the prize, either be points amount or voucher code.
ExpirationDate	datetime	Expiration date of the prize.
Description	string	Description of the prize.
RewardType*	enum	Type of reward.

GroupProgress (List of Triggers Groups): Progress of triggers groups within the challenge.

Property	Type	Description
GroupId	int	Unique identifier of the group.
GroupOrder	int	Order of the group.
Operator	enum	Logical operator used between groups (e.g., AND, OR).
TriggersProgress*	list	List of triggers within the group.

TriggersProgress (List of Triggers Progress): Progress of individual triggers within the challenge.

Property	Type	Description
TriggerId	int	Unique identifier of the trigger.
TriggerType*	enum	Type of the trigger (e.g., Voucher, Points).
TriggerName	string	Name of the trigger.
TriggerOrder	int	Order of the trigger within the group.
Operator*	enum	Logical operator used between triggers (e.g., AND, OR).
TriggerFrequency	decimal	The amount of actions required to complete the trigger.
ActionLeft	decimal	Number of actions left to complete the trigger.
Progress	decimal	Progress percentage of the trigger.

TriggerId Values

• Earned Points = 1

• Subscribe Vouchers Count = 2

• Redeemed Points = 3

• Redeemed Vouchers Count = 4

• Total Points Balance = 5

• Hit Tier = 6

Enums

Operator

Operator

• And = 1

• Or = 2

---

enum OperatorEnum
{
    And = 1,
    Or = 2,
}

RewardType

Reward Type

• Voucher = 1

• Points = 2

• Badge = 3

---

enum RewardType
{
    Voucher = 1,
    Points = 2,
    Badge = 3
}

DurationType

Duration Type

• Day = 1

• Week = 2

• Month = 3

• Year = 4

---

enum RewardDurationType
{
    Day = 1,
    Week = 2,
    Month = 3,
    Year = 4
}

TriggerType

TriggerType

• Voucher = 1

• Points = 2

• Tier = 3

---

enum TriggerTypeEnum
{
    Voucher = 1,
    Points = 2,
    Tier=3
}

Example Scenario: Triggering a Reward by Earning Points

Let's consider a scenario where the user is participating in a challenge with the following trigger:

• Trigger Name: "Earn 1000 Points"

• Trigger ID: 1

• Trigger Type: 2

• Trigger Frequency: 1000 (the required amount of points to complete the trigger)

Initial State

• Actions Left: 1000 points (This is the total amount of points the user needs to earn to complete the trigger)

• Progress: 0% (No points have been earned yet)

User Actions

As the user earns points, the "Actions Left" will decrease, and the "Progress" will increase accordingly.

• After Earning 200 Points:

  • Actions Left: 800 points (1000 - 200)

  • Progress: 20% (200/1000 points earned)

• After Earning Another 300 Points:

  • Actions Left: 500 points (1000 - 500)

  • Progress: 50% (500/1000 points earned)

• After Earning Another 500 Points:

  • Actions Left: 0 points (1000 - 1000)

  • Progress: 100% (1000/1000 points earned)

Trigger Completion

Once the user earns a total of 1000 points, the trigger is completed:

• Trigger Status: Completed

The system automatically updates the user's challenge progress, marking the trigger as completed.

Reward Issuance

Upon completing the trigger, the user is rewarded as defined by the challenge:

• Reward: "You have won 40% off Buffalo Burger" or other rewards specified by the challenge configuration.

Response Sample

200

Success respone

{
    "result": {
        "data": [
            {
                "name": "Voucher Challenge",
                "description": "Voucher Challenge",
                "startDate": "2024-08-12T11:03:00",
                "endDate": "2024-08-28T11:03:00",
                "endsAfter": 16.0,
                "image": "https://storage.googleapis.com/dsq-staging/staging/Gamification/images/Staging/Challenges/Voucher%20Challenge_1.jpg?X-Goog-Algorithm=GOOG4-RSA-SHA256&X-Goog-Credential=upload-service%40warm-ring-360408.iam.gserviceaccount.com%2F20240812%2Fauto%2Fstorage%2Fgoog4_request&X-Goog-Date=20240812T121119Z&X-Goog-Expires=21600&X-Goog-SignedHeaders=host&X-Goog-Signature=1ad4757466a4f818c4ad889b868c09efef53dd80dd8cb11452643eff7987f70e5abafcdee9b9b748104892423708e7d16bb46a9d4e6dc30b1960820594d93281d3a56b67200f88c05db26018cff6211787e21acc6f5e193cc79159115b02e4980174e05a4519fe9096f0f14a9f5cb4ee31fa9300c9ac6652bcf48d5bf07229b4ee8830705f61c1ccff1c26b17c41f812ba947343f78db8c6bbb672cb65df93c3f25937d2aa8eb79c8c3815b9e801ccff41b3c935009893373896737f284eae438e247facdd647f974e8956ee2022e9d99f052c41863cb20f8c8b08eb235d48f82118efda4f74f366a133df3754a0ebe5785774c15a21a8ed33be4749dd801024",
                "category": {
                    "name": "Food",
                    "id": 1
                },
                "prizes": [
                    {
                        "userId": "01010123422",
                        "milestoneId": 543,
                        "prizes": [
                            {
                                "value": "Ga831886756298",
                                "description": "you have won 40% off Buffalo Burger",
                                "expirationDate": "2024-12-31T00:00:00",
                                "rewardType": 1
                            }
                        ]
                    }
                ],
                "groupProgress": [
                    {
                        "groupId": 305,
                        "operator": 1,
                        "groupOrder": 1,
                        "triggersProgress": [
                            {
                                "triggerName": "Earned Points",
                                "triggerId": 1,
                                "triggerFrequency": 1000.0000,
                                "triggerOrder": 1,
                                "progress": 0.0,
                                "operator": 1,
                                "actionLeft": 1000.0000,
                                "triggerType": 2
                            }
                        ]
                    }
                ],
                "visible": true,
                "id": 308
            }
        ],
        "count": 1,
        "pagesNum": 1
    },
    "message": "Process completed successfully",
    "statusCode": 1,
    "statusName": "Successfully"
}

401

Unauthorized

content-length: 0 
date: Tue, 05 Jan 2021 21:46:37 GMT 
strict-transport-security: max-age=15724800; includeSubDomains 
www-authenticate: Bearer 

Additional Notes

• The user’s progress is tracked in real-time as they complete each action.

• The API supports pagination and sorting to handle large datasets efficiently.

• Prizes object only holds the prize if it is not claimed, once claimed it will be empty and prize moves to history.

• Challenge images are retrieved with pre-signed URLs for secure access.

• The reward is automatically issued upon meeting the challenge's trigger condition.

• Users can view their progress and reward status through the application’s challenge tracking section.

• Challenges are filtered to exclude those that are not visible or limited challenges that have claimed milestones.