Creating and Managing Puzzles
Creating/managing puzzles allows you to create engaging puzzles through the partner API.
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
URL of the image file.
Description of the Puzzle object.
Name/title of the Puzzle object.
Array of reward IDs that are associated with the puzzle. Example [1] or [1,2,3].
Instructions for earning the puzzle.
POST /partner-api/v2/admin/puzzles HTTP/1.1
Host: loyalty.headliner.page
X-API-Key: YOUR_API_KEY
Content-Type: application/x-www-form-urlencoded
Accept: */*
Content-Length: 98
"image_url='text'&description='text'&name='text'&reward_ids=[]&earn_instructions='text'"Successful response
{
"puzzle": {}
}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": []
}
]
}
}2. Update a Puzzle:
PATCH /partner-api/v2/admin/puzzles/:puzzle_id
Name/title of the Puzzle object.
Description of the Puzzle object.
URL of the image file.
Array of reward IDs that are associated with the puzzle. Example [1] or [1,2,3].
Instructions for earning the puzzle.
PATCH /partner-api/v2/admin/puzzles/{puzzle_id} HTTP/1.1
Host: loyalty.headliner.page
X-API-Key: YOUR_API_KEY
Content-Type: application/x-www-form-urlencoded
Accept: */*
Content-Length: 98
"name='text'&description='text'&image_url='text'&reward_ids=[]&earn_instructions='text'"Successful response
{
"puzzle": {}
}Example Request
curl -X PATCH 'https://loyalty.hang.xyz/partner-api/v2/admin/puzzles/05e445f6-7dfd-485a-affb-0b91923e2266' \
-H 'X-API-KEY: YOUR_API_KEY' \
-H 'Content-Type: application/json' \
--data-raw '{
"name":"Updated Puzzle",
"description": "This puzzle is an example",
"image_url": "https://some_different_url.jpg",
"reward_ids": [70],
"earn_instructions": "Updated puzzle description"
}
'Example Response
{
"puzzle": {
"id": "05e445f6-7dfd-485a-affb-0b91923e2266",
"program_id": 1,
"name": "Updated Puzzle",
"description": "This puzzle is an example",
"earn_instructions": "Updated 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",
"priority": null,
// ... (other fields)
}
]
}
}3. Create Puzzle Pieces:
POST /partner-api/v2/admin/puzzle-pieces
This endpoint requires a loyalty_reward_id for each piece, which an be unique or the same.
The loyalty_reward_id must have reward_type of “puzzle_piece” and reward_group of “bonus_reward”.
Puzzle pieces must be created in consecutive slot order starting with slot 0.
The slot/position of the puzzle piece.
The ID of the puzzle piece reward associated with this piece.
The ID of the puzzle this piece would belong to.
POST /partner-api/v2/admin/puzzle-pieces HTTP/1.1
Host: loyalty.headliner.page
X-API-Key: YOUR_API_KEY
Content-Type: application/x-www-form-urlencoded
Accept: */*
Content-Length: 56
"slot=1&loyalty_reward_id='text'&puzzle_id='text'"Successful response
{
"puzzle_piece": {}
}Example Request
curl -X POST 'https://loyalty.hang.xyz/partner-api/v2/admin/puzzle-pieces' \
-H 'X-API-KEY: YOUR_API_KEY' \
-H 'Content-Type: application/json' \
--data-raw '{
"puzzle_id": "05e445f6-7dfd-485a-affb-0b91923e2266",
"loyalty_reward_id": 73,
"slot": 0
}
'Example Response
{
"puzzle_piece": {
"id": "3770ff13-d6e3-4c6f-bf69-44939116f84d",
"puzzle_id": "05e445f6-7dfd-485a-affb-0b91923e2266",
"loyalty_reward_id": 73,
"slot": 0
}
}4. Update Puzzle Pieces:
PATCH /partner-api/v2/admin/puzzle-pieces/:puzzle_piece_id
This is used to modify existing puzzle pieces.
The ID of the puzzle piece to update.
The ID of the puzzle this piece would belong to.
The ID of the puzzle piece reward associated with this piece.
The slot/position of the puzzle piece.
PATCH /partner-api/v2/admin/puzzle-pieces/{puzzle_piece_id} HTTP/1.1
Host: loyalty.headliner.page
X-API-Key: YOUR_API_KEY
Content-Type: application/x-www-form-urlencoded
Accept: */*
Content-Length: 56
"puzzle_id='text'&loyalty_reward_id='text'&slot=1"Successful response
{
"puzzle_piece": {}
}Example Request
curl -X POST \
'https://loyalty.hang.xyz/partner-api/v2/admin/puzzle-pieces/3770ff13-d6e3-4c6f-bf69-44939116f84d' \
-H 'X-API-KEY: YOUR_API_KEY' \
-H 'Content-Type: application/json' \
--data-raw '{
"puzzle_id": "05e445f6-7dfd-485a-affb-0b91923e2266",
"loyalty_reward_id": 73
}
'Example Response
{
"puzzle_piece": {
"id": "3770ff13-d6e3-4c6f-bf69-44939116f84d",
"puzzle_id": "05e445f6-7dfd-485a-affb-0b91923e2266",
"loyalty_reward_id": 73,
"slot": 1
}
}Managing Puzzle Progression
1. Retrieve All Available Puzzles to a Program Membership
GET /partner-api/v2/program-memberships/:program_membership_id/puzzles
Retrieves puzzles available to a program membership, with an optional filter parameter “started” that shows only puzzles for which pieces have already begun collecting.
ID of the program membership to retrieve puzzles for
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.
GET /partner-api/v2/program-memberships/{program_membership_id}/puzzles HTTP/1.1
Host: loyalty.headliner.page
X-API-Key: YOUR_API_KEY
Accept: */*
Successful response
{
"puzzle": {}
}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)
}
]
}
]
}2. Check Progress of a Specific Puzzle
GET /partner-api/v2/program-memberships/:program_membership_id/puzzles/:puzzle_id
Get detailed progress of a program membership towards completing a specific puzzle.
ID of the puzzle to retrieve
ID of the program membership to retrieve puzzle for
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: */*
Successful response
{
"puzzle": {}
}Example Request
curl -X GET \
'https://loyalty.hang.xyz/partner-api/v2/program-memberships/162bd43c-aefc-4d39-aac7-77143986e10d/puzzles/7c92e165-dab5-437a-8a38-3665ad2e38cc' \
-H 'X-API-KEY: YOUR_API_KEY'Example Response
{
"puzzle": {
"id": "7c92e165-dab5-437a-8a38-3665ad2e38cc",
"name": "Updated Puzzle example",
"description": "This is an example Puzzle",
"pieces": [
{
"reward_id": 70,
"slot": 0,
"is_complete": true
},
{
"reward_id": 73,
"slot": 1,
"is_complete": false
}
],
"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)
}
]
}
}Redeem a Completed Puzzle
POST /partner-api/v2/program-memberships/:program_membership_id/puzzles/:puzzle_id/complete
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.
ID of the puzzle to redeem
ID of the program membership to redeem the puzzle for
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: */*
{
"puzzle": {}
}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.
Last updated