> For the complete documentation index, see [llms.txt](https://docs.hang.com/hang-platform/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.hang.com/hang-platform/api-usage/creating-and-managing-puzzles.md).

# 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": "<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](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.

<br>