Quest actions API
Send the evidence each quest format needs, then complete the quest.
On this page
How completion works
Each quest format collects its own evidence, then the quest is completed. Timed quests use start, progress and complete. Video, banner, survey and quiz quests also read their questions and send answers one at a time. Visit, profile and custom quests send their own evidence first. Event, referral and streak quests need no call here: your server reports activities and AdQuest settles them by itself.
Get the question
/platform/quests/{questId}/questionReturns the questions and their options for a video, banner, survey or quiz quest. The quest must have been started for this user. A video or banner quest can ask up to 10 graded questions.
Authentication: Public API key (X-AdQuest-Platform-Key) and participant token (X-AdQuest-Participant-Token). Both are required.
| Parameter | In | Type | Description |
|---|---|---|---|
questId required | path | integer | Quest ID. |
external_user_id required | query | string | Your ID for the user. |
X-AdQuest-Participant-Token required | header | string | The participant token minted by your backend (POST /platform/participant-sessions). Required: it is the participant's identity. A body external_user_id is optional and must match it (403 PARTICIPANT_MISMATCH); a missing or invalid token is 401 PARTICIPANT_AUTH_REQUIRED. |
curl "https://api.adquest.io/api/v1/platform/quests/23/question" \
-H "X-AdQuest-Platform-Key: YOUR_PUBLIC_API_KEY" \
-H "X-AdQuest-Participant-Token: PARTICIPANT_TOKEN"200 The first question, plus questions with every question of the attempt. For an attempt held by AdQuest, ask_order lists the question ids in the order they are asked (a missed graded question again at the end) and due_at is the current deadline. Also returned with this status: status is false when external_user_id is missing, the quest was not started or its timer expired, or the quest has no question. The message says which.
{
"status": true,
"code": "OK",
"message": "Quest question",
"data": {
"id": 5,
"title": "What did the video explain?",
"input_type": "choice",
"is_required": true,
"options": [
{
"id": 11,
"title": "How to start"
},
{
"id": 12,
"title": "How to pay"
}
],
"questions": []
}
}404 QUEST_NOT_FOUND. The quest does not exist or is not available.
Record watch progress
/platform/quests/{questId}/progressRecords watch evidence for a timed quest. Send it while the participant is really watching.
Authentication: Public API key (X-AdQuest-Platform-Key) and participant token (X-AdQuest-Participant-Token). Both are required.
| Parameter | In | Type | Description |
|---|---|---|---|
questId required | path | integer | Quest ID. |
X-AdQuest-Participant-Token required | header | string | The participant token minted by your backend (POST /platform/participant-sessions). Required: it is the participant's identity. A body external_user_id is optional and must match it (403 PARTICIPANT_MISMATCH); a missing or invalid token is 401 PARTICIPANT_AUTH_REQUIRED. |
external_user_id required | body | string | Your ID for the user. Max 255 characters. |
watch_duration | body | number | Seconds watched so far. |
curl -X POST https://api.adquest.io/api/v1/platform/quests/23/progress \
-H "Content-Type: application/json" \
-H "X-AdQuest-Platform-Key: YOUR_PUBLIC_API_KEY" \
-H "X-AdQuest-Participant-Token: PARTICIPANT_TOKEN" \
-d '{ "external_user_id": "player-42", "watch_duration": 8 }'200 The progress was recorded.
{
"status": true,
"code": "OK",
"message": "Quest progress recorded",
"data": {
"quest_id": 23,
"elapsed_seconds": 8,
"required_seconds": 15
}
}404 QUEST_NOT_FOUND. The quest does not exist or is not available.
422 The evidence was rejected. data.reason says why. If the quest is already completed, data.completed is true.
Attribute a visit
/platform/quests/{questId}/visitRecords that the participant followed the link of a visit quest and returns the destination. Visit quests only.
Authentication: Public API key (X-AdQuest-Platform-Key) and participant token (X-AdQuest-Participant-Token). Both are required.
| Parameter | In | Type | Description |
|---|---|---|---|
questId required | path | integer | Quest ID. |
external_user_id required | query | string | Your ID for the user. May also be sent in the body. |
referrer_external_user_id | query | string | The user who shared the link, if any. |
redirect | query | string | Send 1 to receive an HTTP redirect to the destination instead of JSON. |
X-AdQuest-Participant-Token required | header | string | The participant token minted by your backend (POST /platform/participant-sessions). Required: it is the participant's identity. A body external_user_id is optional and must match it (403 PARTICIPANT_MISMATCH); a missing or invalid token is 401 PARTICIPANT_AUTH_REQUIRED. |
curl "https://api.adquest.io/api/v1/platform/quests/23/visit" \
-H "X-AdQuest-Platform-Key: YOUR_PUBLIC_API_KEY" \
-H "X-AdQuest-Participant-Token: PARTICIPANT_TOKEN"200 The visit was attributed.
{
"status": true,
"code": "OK",
"message": "Visit attributed",
"data": {
"quest_id": 23,
"redirect_url": "https://example.com/offer",
"clicked_at": "2026-01-01T12:00:00.000Z"
}
}400 NOT_VISIT_QUEST. The quest is not a visit quest.
401 PARTICIPANT_AUTH_REQUIRED. external_user_id is missing.
404 QUEST_NOT_FOUND. The quest does not exist or is not available.
Answer one question
/platform/quests/{questId}/answerAnswers the current question of the participant's attempt, in order and before its deadline. The last answer submits the attempt: it is accepted (202) and settled asynchronously; poll the completion status. Needs a reservation (the quest was started with reservations enabled). A request naming an earlier reservation_id is refused with 409 STALE_RESERVATION and changes nothing. A retry of the accepted final answer returns 202 (still processing) or the settled outcome, even after the attempt's deadline; it never creates a second submission.
Authentication: Public API key (X-AdQuest-Platform-Key) and participant token (X-AdQuest-Participant-Token). Both are required.
| Parameter | In | Type | Description |
|---|---|---|---|
questId required | path | integer | Quest ID. |
X-AdQuest-Participant-Token required | header | string | The participant token minted by your backend (POST /platform/participant-sessions). Required: it is the participant's identity. A body external_user_id is optional and must match it (403 PARTICIPANT_MISMATCH); a missing or invalid token is 401 PARTICIPANT_AUTH_REQUIRED. |
question_id required | body | integer | The current question. |
option_id | body | integer | The chosen option (choice questions). |
free_text | body | string | The answer (free-text questions). |
reservation_id | body | string | The reservation_id returned by start (or the X-AdQuest-Reservation header). Required: an answer must name its attempt, and it must be the current one (409 STALE_RESERVATION otherwise, 422 RESERVATION_REQUIRED when missing). |
curl -X POST https://api.adquest.io/api/v1/platform/quests/23/answer \
-H "Content-Type: application/json" \
-H "X-AdQuest-Platform-Key: YOUR_PUBLIC_API_KEY" \
-H "X-AdQuest-Participant-Token: PARTICIPANT_TOKEN" \
-d '{ "question_id": 5 }'200 The answer was recorded; the next question's deadline is in the data. correct is false when a video or banner quiz question was missed for the first time: the attempt goes on and the question is asked once more after the others (ask_order lists the question ids in the order they are asked). A second miss on it ends the attempt (ANSWER_REJECTED).
{
"status": true,
"code": "OK",
"message": "Answer recorded",
"data": {
"state": "reserved",
"correct": true,
"answered_count": 1,
"ask_order": [
5,
6
],
"question_due_at": "2026-11-07T10:00:22+00:00"
}
}202 The final answer was accepted. The attempt is processing: capacity and budget stay reserved until settlement.
{
"status": true,
"code": "ACCEPTED",
"message": "Answer accepted",
"data": {
"state": "processing",
"reservation_id": "0f4f6c52-3c7d-4d6e-9d0f-6f9d3f1d2a11",
"settlement_status": "pending",
"quest_id": 23
}
}409 RESERVATION_EXPIRED, WRONG_QUESTION, STALE_RESERVATION or TOO_EARLY.
422 The answer is not valid for the question.
Read growth status
/platform/quests/{questId}/growth-statusReturns where the participant stands on an event, profile, referral, streak or custom quest. A referral's `referral` block also carries role (inviter | invitee: invited to this quest, with no invites of their own) and inviter_reward / invitee_reward, what one unit pays each side as decimals.
Authentication: Public API key (X-AdQuest-Platform-Key) and participant token (X-AdQuest-Participant-Token). Both are required.
| Parameter | In | Type | Description |
|---|---|---|---|
questId required | path | integer | Quest ID. |
external_user_id required | query | string | Your ID for the user. May also be sent in the body. |
X-AdQuest-Participant-Token required | header | string | The participant token minted by your backend (POST /platform/participant-sessions). Required: it is the participant's identity. A body external_user_id is optional and must match it (403 PARTICIPANT_MISMATCH); a missing or invalid token is 401 PARTICIPANT_AUTH_REQUIRED. |
curl "https://api.adquest.io/api/v1/platform/quests/23/growth-status" \
-H "X-AdQuest-Platform-Key: YOUR_PUBLIC_API_KEY" \
-H "X-AdQuest-Participant-Token: PARTICIPANT_TOKEN"200 data.type is the quest format. An event quest adds data.progress (current, target, unit) and data.activity, counted from the activities your server reports. A profile quest adds data.profile with the completeness check. A referral quest adds data.referral: code, code_source (adquest or platform), invite_link (null with platform codes), attributed_count, min_attributions, reward_target, can_complete, pay_each_invite, paid_units (invites paid so far; 0 unless pay_each_invite), max_units (the most invites that can be paid, or null when nothing caps it) and history, whose items carry payout_unit (the paid invite number, or null). Streak and custom quests add their own state.
401 PARTICIPANT_AUTH_REQUIRED. external_user_id is missing.
404 QUEST_NOT_FOUND. The quest does not exist or is not available.
| data.referral field | Type | Meaning |
|---|---|---|
| code | string or null | The participant’s invite code. |
| code_source | string | adquest (AdQuest codes) or platform (your own codes). |
| invite_link | string or null | The AdQuest invite link. null with platform codes or when there is no code. |
| attributed_count, min_attributions | integer | Friends counted in the attribution window, and the quest’s minimum. |
| reward_target, can_complete | string, boolean | Who is rewarded (inviter, invitee or both), and whether this participant can complete the quest now. |
| pay_each_invite | boolean | True when each invite is paid separately. |
| paid_units, max_units | integer, integer or null | Invites paid so far (0 unless pay_each_invite), and the most that can be paid. null when nothing caps it. |
| history | array | This inviter’s invites. Each has payout_unit: its paid number, or null when it was not paid. |
Complete a quest
/platform/quests/{questId}/completeSubmits the participant’s evidence. AdQuest checks it on the server and, when it is valid, settles the reward. For a quest held as an attempt (video, banner, survey, quiz, visit), name the attempt with reservation_id or the X-AdQuest-Reservation header. A client that declares the async_complete capability gets 202 while the reward is paid; poll the completion status. Graded questions sent here all at once get no second chance: send them one by one to the answer route for that.
Authentication: Public API key (X-AdQuest-Platform-Key) and participant token (X-AdQuest-Participant-Token). Both are required.
| Parameter | In | Type | Description |
|---|---|---|---|
questId required | path | integer | Quest ID. |
Idempotency-Key | header | string | Send as an HTTP header. A repeated key returns the earlier completion and never pays twice. |
X-AdQuest-Reservation | header | string | The reservation_id returned by start. The same as the reservation_id body field. |
X-AdQuest-Participant-Token required | header | string | The participant token minted by your backend (POST /platform/participant-sessions). Required: it is the participant's identity. A body external_user_id is optional and must match it (403 PARTICIPANT_MISMATCH); a missing or invalid token is 401 PARTICIPANT_AUTH_REQUIRED. |
external_user_id required | body | string | Your ID for the user. Max 255 characters. |
question_id | body | integer | Required for video and banner quests, and for surveys when answers is not sent. |
user_input | body | string | The option the participant chose. Required together with question_id. |
answers | body | array | Survey only. One entry per answered question, each with its question_id. |
delivery_token | body | string | Token you received when the quest started. |
watch_duration | body | number | Seconds watched. |
reservation_id | body | string | The reservation_id returned by start, for a quest held as an attempt. A request naming an earlier attempt is refused. |
evidence_type | body | string | Custom quests: url_callback or manual_review. Must match the quest's evidence type. |
evidence | body | string | Custom quests with manual_review: the participant's proof, up to 2000 characters. |
curl -X POST https://api.adquest.io/api/v1/platform/quests/23/complete \
-H "Content-Type: application/json" \
-H "X-AdQuest-Platform-Key: YOUR_PUBLIC_API_KEY" \
-H "X-AdQuest-Participant-Token: PARTICIPANT_TOKEN" \
-d '{
"external_user_id": "player-42",
"question_id": 5,
"user_input": "11"
}'200 The quest was completed. tokens_awarded is the participant’s share. Also returned with this status: status false when the evidence was not enough (data.reason, such as timer_expired, click_required or visit_too_short) or a graded answer was wrong (ANSWER_REJECTED).
{
"status": true,
"code": "OK",
"message": "Quest completed successfully",
"data": {
"status": true,
"quest_id": 23,
"completed_at": "2026-01-01T12:00:00.000Z",
"tokens_awarded": 10,
"token_reward": 10
}
}202 ACCEPTED, for a client that declares async_complete: the submission was accepted and is being paid. data.settlement_status is pending. Poll the completion status.
401 PARTICIPANT_AUTH_REQUIRED. The participant token is missing or invalid.
403 PREVIEW_READONLY. A theme preview cannot complete quests.
404 QUEST_NOT_FOUND. The quest does not exist or is not available.
409 IDEMPOTENCY_KEY_REUSED (the key was used for another request), NOT_STARTED, STALE_RESERVATION (an earlier attempt was named), or MULTI_STEP_REQUIRED (a multi-step quest with required steps still open).
422 Validation failed, the evidence was rejected, or the quest settles itself. STREAK_SETTLES_ITSELF: a streak day counts from the activities your server reports; ACTIVITY_GOAL_NOT_MET: an event Quest completes when its activity goal is met.
503 RETRYABLE_CONFLICT or SETTLEMENT_PENDING. Nothing was lost: retry with the same Idempotency-Key.
Check a completion
/platform/quests/{questId}/completionWhere the participant's attempt stands: reserved, processing, settled, rejected or expired, with the settlement status and the tokens awarded once settled.
Authentication: Public API key (X-AdQuest-Platform-Key) and participant token (X-AdQuest-Participant-Token). Both are required.
| Parameter | In | Type | Description |
|---|---|---|---|
questId required | path | integer | Quest ID. |
X-AdQuest-Participant-Token required | header | string | The participant token minted by your backend (POST /platform/participant-sessions). Required: it is the participant's identity. A body external_user_id is optional and must match it (403 PARTICIPANT_MISMATCH); a missing or invalid token is 401 PARTICIPANT_AUTH_REQUIRED. |
curl "https://api.adquest.io/api/v1/platform/quests/23/completion" \
-H "X-AdQuest-Platform-Key: YOUR_PUBLIC_API_KEY" \
-H "X-AdQuest-Participant-Token: PARTICIPANT_TOKEN"200 The attempt's state. settlement_status is success, pending, failed or none.
{
"status": true,
"code": "OK",
"message": "Completion status",
"data": {
"quest_id": 23,
"state": "settled",
"reservation_id": "0f4f6c52-3c7d-4d6e-9d0f-6f9d3f1d2a11",
"settlement_status": "success",
"tokens_awarded": 7,
"reason": null,
"expires_at": null,
"completed_at": "2026-11-07T10:00:41+00:00"
}
}Read quest stats
/platform/quests/{questId}/statsReturns engagement counts for one quest on your platform.
Authentication: Public API key (X-AdQuest-Platform-Key).
| Parameter | In | Type | Description |
|---|---|---|---|
questId required | path | integer | Quest ID. |
X-AdQuest-Participant-Token | header | string | The participant token. Optional here. It adds per-user state such as completed. |
curl "https://api.adquest.io/api/v1/platform/quests/23/stats" \
-H "X-AdQuest-Platform-Key: YOUR_PUBLIC_API_KEY" \
-H "X-AdQuest-Participant-Token: PARTICIPANT_TOKEN"200 seen_count is participants who started the quest, clicked_count those who clicked, and answered_count those who completed it. engagement_rate is completed ÷ started as a percentage.
{
"status": true,
"code": "OK",
"message": "Quest stats",
"data": {
"id": 23,
"name": "Watch our intro video",
"seen_count": 120,
"clicked_count": 40,
"answered_count": 54,
"engagement_rate": 45
}
}404 QUEST_NOT_FOUND. The quest does not exist or is not available.
Check a manual review
/platform/quests/{questId}/reviewWhere the participant's manual_review submission stands: pending, approved, rejected or expired. Approval completes the quest and settles the reward without a second request; an approved review that is still settling retries here. A rejected or expired review may be resubmitted through the complete endpoint while can_resubmit is true. Returns status none before any submission.
Authentication: Public API key (X-AdQuest-Platform-Key) and participant token (X-AdQuest-Participant-Token). Both are required.
| Parameter | In | Type | Description |
|---|---|---|---|
questId required | path | integer | Quest ID. |
X-AdQuest-Participant-Token required | header | string | The participant token minted by your backend (POST /platform/participant-sessions). Required: it is the participant's identity. A body external_user_id is optional and must match it (403 PARTICIPANT_MISMATCH); a missing or invalid token is 401 PARTICIPANT_AUTH_REQUIRED. |
curl "https://api.adquest.io/api/v1/platform/quests/23/review" \
-H "X-AdQuest-Platform-Key: YOUR_PUBLIC_API_KEY" \
-H "X-AdQuest-Participant-Token: PARTICIPANT_TOKEN"200 The latest review for the participant. settlement_status is pending or settled once approved, otherwise null.
{
"status": true,
"code": "OK",
"message": "Custom review status",
"data": {
"id": 41,
"status": "rejected",
"attempt": 1,
"evidence": "receipt-123",
"approved_at": null,
"rejected_at": "2026-11-08T09:12:00+00:00",
"reject_reason": "Receipt is unreadable",
"expires_at": "2026-11-22T09:00:00+00:00",
"settled_at": null,
"can_resubmit": true,
"settlement_status": null
}
}Read a multi-step execution
/platform/quests/{questId}/executionState of the participant's multi-step execution: the definition version it is bound to, every step with its status (pending, in_review, verified, rejected) and availability, whether all required steps are verified, and the settlement status of the parent quest. Returns 409 NOT_STARTED before start. Returns 404 MULTI_STEP_DISABLED when multi-step quests are off for the environment, and 503 MULTI_STEP_DISABLED when attempt holds (reservations) are off.
Authentication: Public API key (X-AdQuest-Platform-Key) and participant token (X-AdQuest-Participant-Token). Both are required.
| Parameter | In | Type | Description |
|---|---|---|---|
questId required | path | integer | Quest ID. |
X-AdQuest-Participant-Token required | header | string | The participant token minted by your backend (POST /platform/participant-sessions). Required: it is the participant's identity. A body external_user_id is optional and must match it (403 PARTICIPANT_MISMATCH); a missing or invalid token is 401 PARTICIPANT_AUTH_REQUIRED. |
curl "https://api.adquest.io/api/v1/platform/quests/23/execution" \
-H "X-AdQuest-Platform-Key: YOUR_PUBLIC_API_KEY" \
-H "X-AdQuest-Participant-Token: PARTICIPANT_TOKEN"200 The execution state.
{
"status": true,
"code": "OK",
"message": "Execution state",
"data": {
"quest_id": 23,
"execution_id": 7,
"steps_version": 1,
"ordering": "sequential",
"state": "reserved",
"steps": [
{
"step_key": "buy",
"position": 1,
"format": "custom",
"required": true,
"status": "verified",
"attempts": 1,
"available": true
}
],
"steps_complete": false,
"settlement_status": "none",
"unsettled_reason": null,
"tokens_awarded": null
}
}Read one step
/platform/quests/{questId}/steps/{key}Status of one step of the execution, including the latest manual review (never expected answers or callback URLs). When the owner or the platform's activity definition set a host deep link, config carries action_url (https or an app scheme) and an optional action_label; the SDK only navigates to it and the host app still proves the step.
Authentication: Public API key (X-AdQuest-Platform-Key) and participant token (X-AdQuest-Participant-Token). Both are required.
| Parameter | In | Type | Description |
|---|---|---|---|
questId required | path | integer | Quest ID. |
key required | path | string | Step key. |
X-AdQuest-Participant-Token required | header | string | The participant token minted by your backend (POST /platform/participant-sessions). Required: it is the participant's identity. A body external_user_id is optional and must match it (403 PARTICIPANT_MISMATCH); a missing or invalid token is 401 PARTICIPANT_AUTH_REQUIRED. |
curl "https://api.adquest.io/api/v1/platform/quests/23/steps/buy" \
-H "X-AdQuest-Platform-Key: YOUR_PUBLIC_API_KEY" \
-H "X-AdQuest-Participant-Token: PARTICIPANT_TOKEN"200 The execution state.
{
"status": true,
"code": "OK",
"message": "Execution state",
"data": {
"quest_id": 23,
"execution_id": 7,
"steps_version": 1,
"ordering": "sequential",
"state": "reserved",
"steps": [
{
"step_key": "buy",
"position": 1,
"format": "custom",
"required": true,
"status": "verified",
"attempts": 1,
"available": true
}
],
"steps_complete": false,
"settlement_status": "none",
"unsettled_reason": null,
"tokens_awarded": null
}
}Submit step evidence
/platform/quests/{questId}/steps/{key}/evidenceAsk the server to verify a step. The server decides: a body of completed:true is ignored. action=start starts a timed (video/banner) step, action=click records a visit click, evidence/answers/evidence_type carry survey answers or manual-review proof. Condition and streak steps are met by the activities your server reports to POST /server/activities. When the last required step is verified the parent is admitted for settlement without another request; poll the execution or completion for the result.
Authentication: Public API key (X-AdQuest-Platform-Key) and participant token (X-AdQuest-Participant-Token). Both are required.
| Parameter | In | Type | Description |
|---|---|---|---|
questId required | path | integer | Quest ID. |
key required | path | string | Step key. |
X-AdQuest-Participant-Token required | header | string | The participant token minted by your backend (POST /platform/participant-sessions). Required: it is the participant's identity. A body external_user_id is optional and must match it (403 PARTICIPANT_MISMATCH); a missing or invalid token is 401 PARTICIPANT_AUTH_REQUIRED. |
action | body | string | start begins a timed (video/banner) step; click records the click of a visit step. Omit to submit evidence. |
evidence | body | string | Proof text for a manual_review step (max 2000 characters). |
evidence_type | body | string | Evidence type the step expects (must match the step configuration). |
answers | body | array | Survey answers: [{question_id, user_input}]. |
curl -X POST https://api.adquest.io/api/v1/platform/quests/23/steps/buy/evidence \
-H "Content-Type: application/json" \
-H "X-AdQuest-Platform-Key: YOUR_PUBLIC_API_KEY" \
-H "X-AdQuest-Participant-Token: PARTICIPANT_TOKEN" \
-d '{ }'200 The execution state.
{
"status": true,
"code": "OK",
"message": "Execution state",
"data": {
"quest_id": 23,
"execution_id": 7,
"steps_version": 1,
"ordering": "sequential",
"state": "reserved",
"steps": [
{
"step_key": "buy",
"position": 1,
"format": "custom",
"required": true,
"status": "verified",
"attempts": 1,
"available": true
}
],
"steps_complete": false,
"settlement_status": "none",
"unsettled_reason": null,
"tokens_awarded": null
}
}202 Evidence accepted for asynchronous review.
409 STEP_OUT_OF_ORDER, STEP_NOT_STARTED, RESERVATION_EXPIRED, NOT_STARTED or QUEST_PROCESSING.
422 The server could not verify the step from the evidence (CLICK_REQUIRED, TIMER_NOT_FINISHED, CUSTOM_EVIDENCE_MISSING, ...).