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
Example Request
curl-XPOST'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": [] } ] }}
{"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.
Retrieves puzzles available to a program membership, with an optional filter parameter “started” that shows only puzzles for which pieces have already begun collecting.
{"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) } ] } ]}
{"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) } ] }}
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.
{"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.
