# Creating and Managing Puzzles 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](broken://pages/zpAloIGt8Adr9s3Bltyl#v2-admin-puzzles) {% openapi src="/files/87qUJZPPguSifRhVnwoV" path="/v2/admin/puzzles" method="post" %} [Hang.xyz-hang\_partner\_api-2023.09.07-resolved-3.json](https://2857949451-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FnDjUJ7LXq2gMv9rmEsrI%2Fuploads%2FrSZ9MiJK06S3yg6LkflM%2FHang.xyz-hang_partner_api-2023.09.07-resolved-3.json?alt=media\&token=eabad19c-5c01-41eb-9396-5e083980ac49) {% endopenapi %} #### Example Request ```bash 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 ```json { "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": "

Corrupti cum omnis est.

\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](broken://pages/zpAloIGt8Adr9s3Bltyl#v2-admin-puzzles-puzzle_id) {% openapi src="/files/87qUJZPPguSifRhVnwoV" path="/v2/admin/puzzles/{puzzle\_id}" method="patch" %} [Hang.xyz-hang\_partner\_api-2023.09.07-resolved-3.json](https://2857949451-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FnDjUJ7LXq2gMv9rmEsrI%2Fuploads%2FrSZ9MiJK06S3yg6LkflM%2FHang.xyz-hang_partner_api-2023.09.07-resolved-3.json?alt=media\&token=eabad19c-5c01-41eb-9396-5e083980ac49) {% endopenapi %} #### Example Request ```bash 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 ```json { "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](broken://pages/zpAloIGt8Adr9s3Bltyl#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. {% openapi src="/files/87qUJZPPguSifRhVnwoV" path="/v2/admin/puzzle-pieces" method="post" %} [Hang.xyz-hang\_partner\_api-2023.09.07-resolved-3.json](https://2857949451-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FnDjUJ7LXq2gMv9rmEsrI%2Fuploads%2FrSZ9MiJK06S3yg6LkflM%2FHang.xyz-hang_partner_api-2023.09.07-resolved-3.json?alt=media\&token=eabad19c-5c01-41eb-9396-5e083980ac49) {% endopenapi %} #### Example Request ```bash 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 ```json { "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](broken://pages/zpAloIGt8Adr9s3Bltyl#v2-admin-puzzle-pieces-puzzle_piece_id) * This is used to modify existing puzzle pieces. {% openapi src="/files/87qUJZPPguSifRhVnwoV" path="/v2/admin/puzzle-pieces/{puzzle\_piece\_id}" method="patch" %} [Hang.xyz-hang\_partner\_api-2023.09.07-resolved-3.json](https://2857949451-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FnDjUJ7LXq2gMv9rmEsrI%2Fuploads%2FrSZ9MiJK06S3yg6LkflM%2FHang.xyz-hang_partner_api-2023.09.07-resolved-3.json?alt=media\&token=eabad19c-5c01-41eb-9396-5e083980ac49) {% endopenapi %} ### Example Request ```bash 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 ```json { "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](broken://pages/zpAloIGt8Adr9s3Bltyl#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. {% openapi src="/files/87qUJZPPguSifRhVnwoV" path="/v2/program-memberships/{program\_membership\_id}/puzzles" method="get" %} [Hang.xyz-hang\_partner\_api-2023.09.07-resolved-3.json](https://2857949451-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FnDjUJ7LXq2gMv9rmEsrI%2Fuploads%2FrSZ9MiJK06S3yg6LkflM%2FHang.xyz-hang_partner_api-2023.09.07-resolved-3.json?alt=media\&token=eabad19c-5c01-41eb-9396-5e083980ac49) {% endopenapi %} #### Example Request ```bash 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 ```json { "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](broken://pages/zpAloIGt8Adr9s3Bltyl#v2-admin-puzzle-pieces-puzzle_piece_id) * Get detailed progress of a program membership towards completing a specific puzzle. {% openapi src="/files/87qUJZPPguSifRhVnwoV" path="/v2/program-memberships/{program\_membership\_id}/puzzles/{puzzle\_id}" method="get" %} [Hang.xyz-hang\_partner\_api-2023.09.07-resolved-3.json](https://2857949451-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FnDjUJ7LXq2gMv9rmEsrI%2Fuploads%2FrSZ9MiJK06S3yg6LkflM%2FHang.xyz-hang_partner_api-2023.09.07-resolved-3.json?alt=media\&token=eabad19c-5c01-41eb-9396-5e083980ac49) {% endopenapi %} #### Example Request ```bash 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 ```json { "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](broken://pages/zpAloIGt8Adr9s3Bltyl#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. {% openapi src="/files/87qUJZPPguSifRhVnwoV" path="/v2/program-memberships/{program\_membership\_id}/puzzles/{puzzle\_id}/complete" method="post" %} [Hang.xyz-hang\_partner\_api-2023.09.07-resolved-3.json](https://2857949451-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FnDjUJ7LXq2gMv9rmEsrI%2Fuploads%2FrSZ9MiJK06S3yg6LkflM%2FHang.xyz-hang_partner_api-2023.09.07-resolved-3.json?alt=media\&token=eabad19c-5c01-41eb-9396-5e083980ac49) {% endopenapi %} #### Example Request ```bash 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 ```json { "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.
--- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://docs.hang.com/hang-platform/api-usage/creating-and-managing-puzzles.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.