Managing Quests for Program Memberships

Quests are structured activities within a program designed to encourage customer engagement, offer rewards, and support the brand's message.

Users can opt into quests to participate in them and earn rewards. This document describes how to use Hang's Partner API to manage quests for a program membership.

Opt Into a Quest

Opting into a quest for a specific program membership can be accomplished by making a POST request to the /v2/program-memberships/:program_membership_id/quests/:quest_id/opt-in endpoint.

Request Parameters

• quest_id (required): The ID of the quest the user is opting into.

• program_membership_id (required): The user's program membership ID.

Example Request

curl -X POST 'https://loyalty.hang.xyz/partner-api/v2/program-memberships/1234/quests/quest_1/opt-in' \
  -H 'X-API-Key: YOUR_API_KEY'

Response

If successful, the API will return a 200 OK status along with a JSON object containing information about the quest opt-in.

{
  "opt_in": {
    "id": 1,
    "quest_id": 456,
    "created_at": 1631107200,
    "expires_at": 1633785600,
    "status": "opted_in",
    "progress": [
      {
        "activity_id": 1,
        "value": 42,
        "updated_at": 1631107200,
        "fulfilled_at": 1631193600,
        "prize_claimed_at": null
      },
      ...
    ]
  }
}

Retrieve All Quest Opt-Ins for a Program Membership

Fetching all quest opt-ins for a specific program membership is as straightforward as making a GET request to the /v2/program-memberships/:program_membership_id/quests/opt-ins endpoint.

Request Parameters

• program_membership_id (required): The ID of the program membership.

Example Request

curl -X GET 'https://api.yourdomain.com/v2/program-memberships/1234/quests/opt-ins' \
  -H 'X-API-Key: YOUR_API_KEY'

Response

If successful, the API will return a 200 OK status along with a JSON object containing information about all the quest opt-ins for the program membership.

Example Response

{
  "opt_ins": [
    {
      "id": 123,
      "quest_id": 456,
      "created_at": 1631107200,
      "expires_at": 1633785600,
      "status": "active",
      "progress": [
        {
          "activity_id": 1,
          "value": 42,
          "updated_at": 1631107200,
          "fulfilled_at": 1631193600,
          "prize_claimed_at": null
        },
        {
          "activity_id": 2,
          "value": 30,
          "updated_at": 1631210400,
          "fulfilled_at": null,
          "prize_claimed_at": null
        },
        {
          "activity_id": 3,
          "value": 0,
          "updated_at": null,
          "fulfilled_at": null,
          "prize_claimed_at": null
        },
        {
          "activity_id": 4,
          "value": 0,
          "updated_at": null,
          "fulfilled_at": null,
          "prize_claimed_at": null
        }
      ]
    }
  ]
}

Error Handling

For both endpoints, if an error occurs, the API will provide error codes and messages as defined in the documentation. Make sure to handle these appropriately in your application.