Hang Quests API
The Quests API from Hang — 9 operation(s) for quests.
OpenAPI Specification
swagger: '2.0'
info:
title: Hang Partner API (params in:formData) Activities Quests API
description: '
<p>The Partner API allows you to request various resources that can power your loyalty program.</p>
© Hang 2023'
version: 2023.09.07
x-copyright: '© Hang 2023'
basePath: /partner-api
schemes:
- https
consumes:
- application/x-www-form-urlencoded
- multipart/form-data
security:
- ApiKeyAuth: []
tags:
- name: Quests
paths:
/v2/program-memberships/{program_membership_id}/quests/opt-ins:
get:
tags:
- Quests
consumes:
- application/x-www-form-urlencoded
- multipart/form-data
operationId: get_v2_program-memberships_program_membership_id_quests_opt-ins
summary: Endpoint to retrieve all optIns for a program membership
parameters:
- name: program_membership_id
type: string
in: path
required: true
description: the program membership id
responses:
'200':
description: Successful response
schema:
type: object
properties:
opt_ins:
type: array
items:
type: object
properties:
id:
type: string
description: Unique identifier for the OptIn object.
quest_id:
type: string
description: Unique identifier for the Quest object associated with this OptIn.
created_at:
type: number
description: When the OptIn was created, in epoch seconds.
updated_at:
type: number
description: When the OptIn was updated, in epoch seconds.
expires_at:
type: number
description: When the OptIn expires, in epoch seconds.
status:
type: string
enum:
- opted_in
- all_requirements_completed
- prize_claimed
- non_redeemable
description: The current status of the OptIn.
progress:
type: array
items:
type: object
properties:
activity_id:
type: string
description: Unique identifier for the Activity object.
value:
type: number
description: "Count of \"how far along\" the user is, depending on the activity,\n e.g. a value of 4 could represent $4 spent or 4 referrals"
updated_at:
type: number
description: When progress was last made for this activity, in epoch seconds
fulfilled_at:
type: number
description: When the value surpasssed the required amount for the activity, in epoch seconds
prize_claimed_at:
type: number
description: When the prize for the activity was claimed, in epoch seconds
additionalProperties: false
required:
- activity_id
- value
- updated_at
- fulfilled_at
- prize_claimed_at
additionalProperties: false
required:
- id
- quest_id
- created_at
- updated_at
- expires_at
- status
- progress
additionalProperties: false
required:
- opt_ins
description: OptIns are user initiated and represent the acceptance of a Quest.
/v2/admin/quests:
get:
tags:
- Quests
consumes:
- application/x-www-form-urlencoded
- multipart/form-data
operationId: get_v2_admin_quests
summary: Get all quests for program.
parameters:
- name: limit
type: number
in: query
description: Amount of quests to return (max 20).
- name: offset
type: number
in: query
description: Index to start at.
responses:
'200':
description: Successful response
schema:
type: object
properties:
quests:
type: array
items:
type: string
total_records:
type: number
additionalProperties: false
required:
- quests
- total_records
description: ''
/v2/program-memberships/{program_membership_id}/quests/{quest_id}/opt-in:
post:
tags:
- Quests
consumes:
- application/x-www-form-urlencoded
- multipart/form-data
operationId: post_v2_program-memberships_program_membership_id_quests_quest_id_opt-in
summary: Opt a user into a quest.
parameters:
- name: program_membership_id
type: string
in: path
required: true
description: the user's program membership id
- name: quest_id
type: string
in: path
required: true
description: the ID for the quest being opted into
responses:
'200':
description: Successful response
schema:
type: object
properties:
opt_in:
type: object
properties:
id:
type: string
description: Unique identifier for the OptIn object.
quest_id:
type: string
description: Unique identifier for the Quest object associated with this OptIn.
created_at:
type: number
description: When the OptIn was created, in epoch seconds.
updated_at:
type: number
description: When the OptIn was updated, in epoch seconds.
expires_at:
type: number
description: When the OptIn expires, in epoch seconds.
status:
type: string
enum:
- opted_in
- all_requirements_completed
- prize_claimed
- non_redeemable
description: The current status of the OptIn.
progress:
type: array
items:
type: object
properties:
activity_id:
type: string
description: Unique identifier for the Activity object.
value:
type: number
description: "Count of \"how far along\" the user is, depending on the activity,\n e.g. a value of 4 could represent $4 spent or 4 referrals"
updated_at:
type: number
description: When progress was last made for this activity, in epoch seconds
fulfilled_at:
type: number
description: When the value surpasssed the required amount for the activity, in epoch seconds
prize_claimed_at:
type: number
description: When the prize for the activity was claimed, in epoch seconds
additionalProperties: false
required:
- activity_id
- value
- updated_at
- fulfilled_at
- prize_claimed_at
additionalProperties: false
required:
- id
- quest_id
- created_at
- updated_at
- expires_at
- status
- progress
additionalProperties: false
required:
- opt_in
description: OptIns are generally user initiated and represent the acceptance of a Quest.
/opt-ins/{opt_in_id}/claim-quest-prize:
post:
tags:
- Quests
consumes:
- application/x-www-form-urlencoded
- multipart/form-data
operationId: post_opt-ins_opt_in_id_claim-quest-prize
summary: Claim the prize(s) associated with a Quest.
parameters:
- name: opt_in_id
type: string
in: path
required: true
description: the id of the OptIn whose Quest's prize(s) is ready to be claimed.
responses:
'200':
description: Successful response
schema:
type: object
properties:
prize:
type: object
properties:
point_reward_value:
type: number
description: The amount of points, or any tier metric (e.g. xp, points, stars, etc), the user earns for claiming the prize.
sponsor_name:
type: string
description: Quest sponsor name.
lootbox:
type: object
properties:
id:
type: string
description: Unique identifier for the Lootbox object.
name:
type: string
description: Lootbox name.
description:
type: string
description: An arbitrary description attached to the Lootbox object. Often useful for displaying to users.
background_gradient_start_color:
type: string
background_gradient_stop_color:
type: string
container_images:
type: object
properties:
box_together:
type: string
box_top:
type: string
box_bottom:
type: string
additionalProperties: false
required:
- box_together
- box_top
- box_bottom
lootbox_reward_choices:
type: array
items:
type: object
properties:
id:
type: string
description: ID for lootbox reward choice.
title:
type: string
description: Title for lootbox reward choice.
subtitle:
type: string
description: Subtitle for lootbox reward choice.
category:
type: string
description: Category for lootbox reward choice.
point_reward_value:
type: number
description: Points for lootbox reward choice.
reward_uuid:
type: string
description: Reward UUID for lootbox reward choice.
image:
type: string
description: Image for lootbox reward choice.
probability:
type: number
description: Probability for lootbox reward choice.
reward:
type: object
properties:
uuid:
type: string
description: Unique identifier for the Reward object.
name:
type: string
description: Reward name.
description:
type: string
description: An arbitrary description attached to the Reward object. Often useful for displaying to users.
image_url:
type: string
description: An absolute URL of the reward's image.
terms_and_conditions:
type: string
description: Terms and condition for the rewards.
metadata:
type: object
additionalProperties: true
description: Set of key-value pairs that you can attach to a reward. This can be useful for storing additional information about the quest in a structured format.
additionalProperties: false
required:
- uuid
- name
- description
- image_url
- terms_and_conditions
- metadata
additionalProperties: false
required:
- id
- title
- subtitle
- category
- point_reward_value
- reward_uuid
- image
- probability
- reward
metadata:
type: object
additionalProperties: true
description: Set of key-value pairs that you can attach to a lootbox. This can be useful for storing additional information about the lootbox in a structured format.
additionalProperties: false
required:
- id
- name
- description
- background_gradient_start_color
- background_gradient_stop_color
- container_images
- lootbox_reward_choices
- metadata
reward:
type: object
properties:
uuid:
type: string
description: Unique identifier for the Reward object.
name:
type: string
description: Reward name.
description:
type: string
description: An arbitrary description attached to the Reward object. Often useful for displaying to users.
image_url:
type: string
description: An absolute URL of the reward's image.
terms_and_conditions:
type: string
description: Terms and condition for the rewards.
additionalProperties: false
required:
- uuid
- name
- description
- image_url
- terms_and_conditions
additionalProperties: false
required:
- point_reward_value
- sponsor_name
- lootbox
- reward
additionalProperties: false
required:
- prize
description: Prizes can exist on both the Quest and Activity levels. Invoke this endpoint to claim the prizes at the Quest level.
/opt-ins/{opt_in_id}/claim-activity-prize:
post:
tags:
- Quests
consumes:
- application/x-www-form-urlencoded
- multipart/form-data
operationId: post_opt-ins_opt_in_id_claim-activity-prize
summary: Claim the prize(s) associated with an Activity.
parameters:
- name: activity_id
type: string
in: formData
required: true
description: the id of the Activity whose prize(s) you wish to claim
- name: opt_in_id
type: string
in: path
required: true
description: the id of the OptIn whose Activity's prize(s) is ready to be claimed.
responses:
'200':
description: Successful response
schema:
type: object
properties:
prize:
type: object
properties:
point_reward_value:
type: number
description: The amount of points, or any tier metric (e.g. xp, points, stars, etc), the user earns for claiming the prize.
sponsor_name:
type: string
description: Quest sponsor name.
lootbox:
type: object
properties:
id:
type: string
description: Unique identifier for the Lootbox object.
name:
type: string
description: Lootbox name.
description:
type: string
description: An arbitrary description attached to the Lootbox object. Often useful for displaying to users.
background_gradient_start_color:
type: string
background_gradient_stop_color:
type: string
container_images:
type: object
properties:
box_together:
type: string
box_top:
type: string
box_bottom:
type: string
additionalProperties: false
required:
- box_together
- box_top
- box_bottom
lootbox_reward_choices:
type: array
items:
type: object
properties:
id:
type: string
description: ID for lootbox reward choice.
title:
type: string
description: Title for lootbox reward choice.
subtitle:
type: string
description: Subtitle for lootbox reward choice.
category:
type: string
description: Category for lootbox reward choice.
point_reward_value:
type: number
description: Points for lootbox reward choice.
reward_uuid:
type: string
description: Reward UUID for lootbox reward choice.
image:
type: string
description: Image for lootbox reward choice.
probability:
type: number
description: Probability for lootbox reward choice.
reward:
type: object
properties:
uuid:
type: string
description: Unique identifier for the Reward object.
name:
type: string
description: Reward name.
description:
type: string
description: An arbitrary description attached to the Reward object. Often useful for displaying to users.
image_url:
type: string
description: An absolute URL of the reward's image.
terms_and_conditions:
type: string
description: Terms and condition for the rewards.
metadata:
type: object
additionalProperties: true
description: Set of key-value pairs that you can attach to a reward. This can be useful for storing additional information about the quest in a structured format.
additionalProperties: false
required:
- uuid
- name
- description
- image_url
- terms_and_conditions
- metadata
additionalProperties: false
required:
- id
- title
- subtitle
- category
- point_reward_value
- reward_uuid
- image
- probability
- reward
metadata:
type: object
additionalProperties: true
description: Set of key-value pairs that you can attach to a lootbox. This can be useful for storing additional information about the lootbox in a structured format.
additionalProperties: false
required:
- id
- name
- description
- background_gradient_start_color
- background_gradient_stop_color
- container_images
- lootbox_reward_choices
- metadata
reward:
type: object
properties:
uuid:
type: string
description: Unique identifier for the Reward object.
name:
type: string
description: Reward name.
description:
type: string
description: An arbitrary description attached to the Reward object. Often useful for displaying to users.
image_url:
type: string
description: An absolute URL of the reward's image.
terms_and_conditions:
type: string
description: Terms and condition for the rewards.
additionalProperties: false
required:
- uuid
- name
- description
- image_url
- terms_and_conditions
additionalProperties: false
required:
- point_reward_value
- sponsor_name
- lootbox
- reward
additionalProperties: false
required:
- prize
description: Prizes can exist on both the Quest and Activity levels. Invoke this endpoint to claim the prizes at the Activity level.
/v2/admin/quests/{quest_id}/quest-requirements:
post:
tags:
- Quests
consumes:
- application/x-www-form-urlencoded
- multipart/form-data
operationId: post_v2_admin_quests_quest_id_quest-requirements
summary: Create a new quest requirement.
parameters:
- name: value_threshold
type: number
in: formData
required: true
description: the ActivityType value threshold needed to satisfy the QuestRequirement
- name: description
type: string
in: formData
required: true
description: a description of the quest requirement
- name: activity_type_id
type: string
in: formData
required: true
description: the ID of the ActivityType that satisfies the QuestRequirement
- name: quest_id
type: string
in: path
required: true
description: the ID of the quest having a requirement added
- name: prize_point_reward_value
type: number
in: formData
description: the amount of points to reward for completing the QuestRequirement
- name: prize_loot_box_id
type: string
in: formData
description: the ID of a lootbox to reward for completing the QuestRequirement
- name: prize_nft_loyalty_reward_id
type: string
in: formData
description: the ID of a reward to reward for completing the QuestRequirement
- name: auto_claim_prize
type: boolean
in: formData
description: a boolean indicating if the prize should be automatically claimed when the QuestRequirement is completed
- name: activity_type_subtypes
type: array
items:
type: string
in: formData
description: an array of ActivityTypeSubtype IDs that can be used to fulfill the QuestRequirement
- name: check_in_interval_days
type: number
in: formData
description: If present, the cadence at which the user must perform the activity (e.g. a value of 3, with a value_threshold of 50 equates to spend $50 every 3 days).
- name: cta_text
type: string
in: formData
description: Call to action description text.
- name: cta_url
type: string
in: formData
description: Call to action URL.
- name: order
type: number
in: formData
description: If present, the order in which the requirement must be completed.
- name: restricted_to_ids
type: array
items:
type: string
in: formData
description: a list containing IDs that are allowed to fulfill the QuestRequirement
responses:
'200':
description: Successful response
schema:
type: object
properties:
quest_requirement:
type: object
properties:
id:
type: string
description: Unique identifier for the QuestRequirement object.
quest_id:
type: string
description: Unique identifier for the Quest object associated with this QuestRequirement.
created_at:
type: number
description: When the QuestRequirement was created, in epoch seconds.
description:
type: string
description: A description of the QuestRequirement.
value_threshold:
type: string
description: The Activity threshold (e.g. a value of 50 dollars spent) that customers need to meet in order to unlock the activity's prize.
order:
type: number
description: If present, the order in which the requirement must be completed.
check_in_interval_days:
type: number
description: If present, the cadence at which the user must perform the activity (e.g. a value of 3, with a value_threshold of 50 equates to spend $50 every 3 days).
image_url:
type: string
description: An absolute URL of the activity's image.
prize:
type: object
properties:
point_reward_value:
type: number
description: The amount of points, or any tier metric (e.g. xp, points, stars, etc), the user earns for claiming the prize.
sponsor_name:
type: string
description: Quest sponsor name.
lootbox:
type: object
properties:
id:
type: string
description: Unique identifier for the Lootbox object.
name:
type: string
description: Lootbox name.
description:
type: string
description: An arbitrary description attached to the Lootbox object. Often useful for displaying to users.
background_gradient_start_color:
type: string
background_gradient_stop_color:
type: string
image_box_together_url:
type: string
reward_choices:
type: array
items:
type: object
properties:
id:
type: string
description: ID for lootbox reward choice.
title:
type: string
description: Title for lootbox reward choice.
subtitle:
type: string
description: Subtitle for lootbox reward choice.
category:
type: string
description: Category for lootbox reward choice.
point_reward_value:
type: number
description: Points for lootbox reward choice.
reward_uuids:
items:
type: string
type: array
description: Reward UUIDs for the loot box reward choice.
quantity:
type: number
description: Max amount of this loot box reward choice to be awarded.
image:
type: string
description: Image for lootbox reward choice.
video:
type: string
description: Video for lootbox reward choice.
proba
# --- truncated at 32 KB (85 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/hang/refs/heads/main/openapi/hang-quests-api-openapi.yml