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

Endpoint to create a puzzle

post

Authorizations

ApiKeyAuth

X-API-KeystringRequired

Body

application/x-www-form-urlencoded

image_urlstringRequired

URL of the image file.

descriptionstringRequired

Description of the Puzzle object.

namestringRequired

Name/title of the Puzzle object.

reward_idsarrayOptional

Array of reward IDs that are associated with the puzzle. Example [1] or [1,2,3].

earn_instructionsstringOptional

Instructions for earning the puzzle.

Responses

200

Successful response

application/json

post

/v2/admin/puzzles

HTTPcURLJavaScriptPython

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'"

200

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

Endpoint to update a puzzle

patch

Authorizations

ApiKeyAuth

X-API-KeystringRequired

Path parameters

puzzle_idnumberRequired

Body

application/x-www-form-urlencoded

namestringOptional

Name/title of the Puzzle object.

descriptionstringOptional

Description of the Puzzle object.

image_urlstringOptional

URL of the image file.

reward_idsarrayOptional

Array of reward IDs that are associated with the puzzle. Example [1] or [1,2,3].

earn_instructionsstringOptional

Instructions for earning the puzzle.

Responses

200

Successful response

application/json

patch

/v2/admin/puzzles/{puzzle_id}

HTTPcURLJavaScriptPython

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'"

200

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.

Create a new piece for a Puzzle.

post

Authorizations

ApiKeyAuth

X-API-KeystringRequired

Body

application/x-www-form-urlencoded

slotnumberRequired

The slot/position of the puzzle piece.

loyalty_reward_idstringRequired

The ID of the puzzle piece reward associated with this piece.

puzzle_idstringRequired

The ID of the puzzle this piece would belong to.

Responses

200

Successful response

application/json

post

/v2/admin/puzzle-pieces

HTTPcURLJavaScriptPython

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'"

200

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.

Update an existing Puzzle Piece.

patch

Authorizations

ApiKeyAuth

X-API-KeystringRequired

Path parameters

puzzle_piece_idstringRequired

The ID of the puzzle piece to update.

Body

application/x-www-form-urlencoded

puzzle_idstringOptional

The ID of the puzzle this piece would belong to.

loyalty_reward_idstringOptional

The ID of the puzzle piece reward associated with this piece.

slotnumberOptional

The slot/position of the puzzle piece.

Responses

200

Successful response

application/json

patch

/v2/admin/puzzle-pieces/{puzzle_piece_id}

HTTPcURLJavaScriptPython

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"

200

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.

Endpoint to retrieve puzzles

get

Authorizations

ApiKeyAuth

X-API-KeystringRequired

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

200

Successful response

application/json

get

/v2/program-memberships/{program_membership_id}/puzzles

HTTPcURLJavaScriptPython

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": {}
}

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.

Endpoint to retrieve a single puzzle

get

Authorizations

ApiKeyAuth

X-API-KeystringRequired

Path parameters

puzzle_idstringRequired

ID of the puzzle to retrieve

program_membership_idstringRequired

ID of the program membership to retrieve puzzle for

Responses

200

Successful response

application/json

get

/v2/program-memberships/{program_membership_id}/puzzles/{puzzle_id}

HTTPcURLJavaScriptPython

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": {}
}

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.

Endpoint to redeem a completed puzzle

post

Authorizations

ApiKeyAuth

X-API-KeystringRequired

Path parameters

puzzle_idstringRequired

ID of the puzzle to redeem

program_membership_idstringRequired

ID of the program membership to redeem the puzzle for

Responses

200

Successful response

application/json

401

The program membership is not authorized to redeem the puzzle with given puzzle_id.

422

The puzzle is not redeemable because it is not complete or the puzzle_id given is not correct.

post

/v2/program-memberships/{program_membership_id}/puzzles/{puzzle_id}/complete

HTTPcURLJavaScriptPython

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.