The Puzzles API facilitates interactive user engagement through puzzles. Users complete various activities to earn pieces, culminating in a reward upon puzzle completion. This API provides endpoints for creating, updating, retrieving puzzles and their pieces, and redeeming rewards for completed puzzles.
How Puzzles Work at Hang
Puzzles incentivize user engagement by offering rewards for collecting all the pieces through completing specific activities. Upon collecting all pieces, users can redeem them for a larger reward.
Setting Up a Puzzle
1. Create a Puzzle:
POST/partner-api/v2/admin/puzzles
Example Request
curl -X POST 'https://loyalty.hang.xyz/partner-api/v2/admin/puzzles' \
-H 'X-API-KEY: YOUR_API_KEY' \
-H 'Content-Type: application/json' \
--data-raw '{
"name":"Reward Puzzle",
"description": "This puzzle is an example",
"image_url": "https://valid-image-url.jpg",
"reward_ids": [69],
"earn_instructions": "This is how you earn this puzzle"
}'
Example Response
{
"puzzle": {
"id": "7c92e165-dab5-437a-8a38-3665ad2e38cc",
"program_id": 1,
"name": "Reward Puzzle",
"description": "This puzzle is an example",
"earn_instructions": "This is how you earn this puzzle",
"image_url": "https://s3-us-west-1.amazonaws.com/dev-images.agoratix.com/puzzles/images/7c9/2e1/65-/original/360_F_92535664_IvFsQeHjBzfE6sD4VHdO8u5OHUSc6yHF.jpg",
"rewards": [
{
"id": 69,
"uuid": "4f4efb6a-e513-45b6-ac33-e101b7518c46",
"name": "Free Puzzle Prize",
"priority": null,
"redemption_instruction": null,
"redemption_method": "code",
"pos_instruction": "<p>Corrupti cum omnis est.</p>\n",
"interval": 0,
"limit": null,
"start_date": "2023-04-06T16:00:00.000Z",
"show_code": true,
"end_date": null,
"controlled_by": "auto",
"reward_type": "redemption",
"status": "PUBLISHED",
"invalidated_at": null,
"image_url": "https://s3-us-west-1.amazonaws.com/dev-images.agoratix.com/live/nft_loyalty_rewards/images/000/000/069/normal/3714f_Property_1_Variant2.png",
"video_url": null,
"brand_codes_csv_upload": null,
"applies_to": []
}
]
}
}
Retrieves puzzles available to a program membership, with an optional filter parameter “started” that shows only puzzles for which pieces have already begun collecting.
Example Request
curl -X GET \
'https://loyalty.hang.xyz/partner-api/v2/program-memberships/162bd43c-aefc-4d39-aac7-77143986e10d/puzzles' \
-H 'X-API-KEY: YOUR_API_KEY'
Example Response
{
"puzzles": [
{
"id": "05e445f6-7dfd-485a-affb-0b91923e2266",
"name": "Puzzle Example",
"description": "This puzzle is a test",
"pieces": [],
"earn_instructions": "This is how you earn this puzzle",
"image_url": "https://s3-us-west-1.amazonaws.com/some-url.jpg",
"rewards": [
{
"id": 69,
"uuid": "4f4efb6a-e513-45b6-ac33-e101b7518c46",
"name": "Free Puzzle Prize",
// ... (other fields)
},
{
"id": 72,
"uuid": "ec735b7a-b002-4871-b041-45068960a590",
"name": "puzzle piece 1",
// ... (other fields)
}
]
},
{
"id": "7c92e165-dab5-437a-8a38-3665ad2e38cc",
"name": "Updated Puzzle",
"description": "This puzzle is an example",
"pieces": [
{
"reward_id": 70,
"slot": 0,
"is_complete": true
},
{
"reward_id": 73,
"slot": 1,
"is_complete": false
}
],
"earn_instructions": "Updated This is how you earn this puzzle",
"image_url": "https://s3-us-west-1.amazonaws.com/some-url.jpg",
"rewards": [
{
"id": 89,
"uuid": "ec735b7a-b002-4871-b041-45068960a590",
"name": "puzzle piece example",
// ... (other fields)
}
]
}
]
}
Redeems a puzzle and allocates its reward to the program membership for as long as all pieces for the puzzle are collected by the provided program membership.
Example Request
curl -X POST \
'https://loyalty.hang.xyz/partner-api/v2/program-memberships/162bd43c-aefc-4d39-aac7-77143986e10d/puzzles/7c92e165-dab5-437a-8a38-3665ad2e38cc/complete' \
-H 'X-API-KEY: YOUR_API_KEY'
Example Response
{
"puzzle": {
"id": "7c92e165-dab5-437a-8a38-3665ad2e38cc",
"program_id": 1,
"name": "Example Puzzle",
"description": "This puzzle is an example",
"earn_instructions": "This is how you earn this puzzle",
"image_url": "https://s3-us-west-1.amazonaws.com/some-url.jpg",
"rewards": [
{
"id": 70,
"uuid": "ec735b7a-b002-4871-b041-45068960a590",
"name": "puzzle piece 1",
// ... (other fields)
}
]
}
}
Error Handling
The API provides error messages for guidance in case of issues. This assists in rapid resolution and smooth operation.
Parameters and Responses
Each endpoint requires specific parameters. For full details on request parameters and expected responses, please refer to the individual endpoint documentation in our API reference.
Endpoint to retrieve puzzles
get
Authorizations
Path parameters
program_membership_idstringRequired
ID of the program membership to retrieve puzzles for
Query parameters
startedbooleanOptional
A filter. Set true to only return puzzles where the program membership has made progress. Set false to only return puzzles where the program membership has not made progress. If left blank, all puzzles are returned.
Responses
get
GET /partner-api/v2/program-memberships/{program_membership_id}/puzzles HTTP/1.1
Host: loyalty.headliner.page
X-API-Key: YOUR_API_KEY
Accept: */*
200
Successful response
{
"puzzle": {}
}
Endpoint to retrieve a single puzzle
get
Authorizations
Path parameters
puzzle_idstringRequired
ID of the puzzle to retrieve
program_membership_idstringRequired
ID of the program membership to retrieve puzzle for
Responses
get
GET /partner-api/v2/program-memberships/{program_membership_id}/puzzles/{puzzle_id} HTTP/1.1
Host: loyalty.headliner.page
X-API-Key: YOUR_API_KEY
Accept: */*
200
Successful response
{
"puzzle": {}
}
Endpoint to redeem a completed puzzle
post
Authorizations
Path parameters
puzzle_idstringRequired
ID of the puzzle to redeem
program_membership_idstringRequired
ID of the program membership to redeem the puzzle for
Responses
post
POST /partner-api/v2/program-memberships/{program_membership_id}/puzzles/{puzzle_id}/complete HTTP/1.1
Host: loyalty.headliner.page
X-API-Key: YOUR_API_KEY
Accept: */*
