# Quest actions API

> Send the evidence each quest format needs, then complete the quest.

Source: https://dashboard.adquest.io/docs/api/quest-actions · Audience: Developers · Section: API reference

## 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.

- [Quest evidence](https://dashboard.adquest.io/docs/quest-evidence): The evidence each format requires.
- [Report activities](https://dashboard.adquest.io/docs/quest-evidence/activities): The one server call for event, referral and streak quests.
- [Quests API](https://dashboard.adquest.io/docs/api/quests): List, read, start, click and view.

## Get the question

### `GET /platform/quests/{questId}/question`

Returns 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 | Required | Description |
| --- | --- | --- | --- | --- |
| questId | path | integer | yes | Quest ID. |
| external_user_id | query | string | yes | Your ID for the user. |
| X-AdQuest-Participant-Token | header | string | yes | 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. |

```bash
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"
```

**Response 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.

```json
{
  "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": []
  }
}
```

**Response 404.** QUEST_NOT_FOUND. The quest does not exist or is not available.

## Record watch progress

### `POST /platform/quests/{questId}/progress`

Records 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 | Required | Description |
| --- | --- | --- | --- | --- |
| questId | path | integer | yes | Quest ID. |
| X-AdQuest-Participant-Token | header | string | yes | 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 | body | string | yes | Your ID for the user. Max 255 characters. |
| watch_duration | body | number | no | Seconds watched so far. |

```bash
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 }'
```

**Response 200.** The progress was recorded.

```json
{
  "status": true,
  "code": "OK",
  "message": "Quest progress recorded",
  "data": {
    "quest_id": 23,
    "elapsed_seconds": 8,
    "required_seconds": 15
  }
}
```

**Response 404.** QUEST_NOT_FOUND. The quest does not exist or is not available.

**Response 422.** The evidence was rejected. data.reason says why. If the quest is already completed, data.completed is true.

## Attribute a visit

### `GET /platform/quests/{questId}/visit`

Records 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 | Required | Description |
| --- | --- | --- | --- | --- |
| questId | path | integer | yes | Quest ID. |
| external_user_id | query | string | yes | Your ID for the user. May also be sent in the body. |
| referrer_external_user_id | query | string | no | The user who shared the link, if any. |
| redirect | query | string | no | Send 1 to receive an HTTP redirect to the destination instead of JSON. |
| X-AdQuest-Participant-Token | header | string | yes | 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. |

```bash
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"
```

**Response 200.** The visit was attributed.

```json
{
  "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"
  }
}
```

**Response 400.** NOT_VISIT_QUEST. The quest is not a visit quest.

**Response 401.** PARTICIPANT_AUTH_REQUIRED. external_user_id is missing.

**Response 404.** QUEST_NOT_FOUND. The quest does not exist or is not available.

## Answer one question

### `POST /platform/quests/{questId}/answer`

Answers 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 | Required | Description |
| --- | --- | --- | --- | --- |
| questId | path | integer | yes | Quest ID. |
| X-AdQuest-Participant-Token | header | string | yes | 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 | body | integer | yes | The current question. |
| option_id | body | integer | no | The chosen option (choice questions). |
| free_text | body | string | no | The answer (free-text questions). |
| reservation_id | body | string | no | 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). |

```bash
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 }'
```

**Response 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).

```json
{
  "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"
  }
}
```

**Response 202.** The final answer was accepted. The attempt is processing: capacity and budget stay reserved until settlement.

```json
{
  "status": true,
  "code": "ACCEPTED",
  "message": "Answer accepted",
  "data": {
    "state": "processing",
    "reservation_id": "0f4f6c52-3c7d-4d6e-9d0f-6f9d3f1d2a11",
    "settlement_status": "pending",
    "quest_id": 23
  }
}
```

**Response 409.** RESERVATION_EXPIRED, WRONG_QUESTION, STALE_RESERVATION or TOO_EARLY.

**Response 422.** The answer is not valid for the question.

## Read growth status

### `GET /platform/quests/{questId}/growth-status`

Returns 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 | Required | Description |
| --- | --- | --- | --- | --- |
| questId | path | integer | yes | Quest ID. |
| external_user_id | query | string | yes | Your ID for the user. May also be sent in the body. |
| X-AdQuest-Participant-Token | header | string | yes | 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. |

```bash
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"
```

**Response 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.

**Response 401.** PARTICIPANT_AUTH_REQUIRED. external_user_id is missing.

**Response 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

### `POST /platform/quests/{questId}/complete`

Submits 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 | Required | Description |
| --- | --- | --- | --- | --- |
| questId | path | integer | yes | Quest ID. |
| Idempotency-Key | header | string | no | Send as an HTTP header. A repeated key returns the earlier completion and never pays twice. |
| X-AdQuest-Reservation | header | string | no | The reservation_id returned by start. The same as the reservation_id body field. |
| X-AdQuest-Participant-Token | header | string | yes | 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 | body | string | yes | Your ID for the user. Max 255 characters. |
| question_id | body | integer | no | Required for video and banner quests, and for surveys when answers is not sent. |
| user_input | body | string | no | The option the participant chose. Required together with question_id. |
| answers | body | array | no | Survey only. One entry per answered question, each with its question_id. |
| delivery_token | body | string | no | Token you received when the quest started. |
| watch_duration | body | number | no | Seconds watched. |
| reservation_id | body | string | no | 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 | no | Custom quests: url_callback or manual_review. Must match the quest's evidence type. |
| evidence | body | string | no | Custom quests with manual_review: the participant's proof, up to 2000 characters. |

```bash
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"
}'
```

**Response 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).

```json
{
  "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
  }
}
```

**Response 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.

**Response 401.** PARTICIPANT_AUTH_REQUIRED. The participant token is missing or invalid.

**Response 403.** PREVIEW_READONLY. A theme preview cannot complete quests.

**Response 404.** QUEST_NOT_FOUND. The quest does not exist or is not available.

**Response 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).

**Response 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.

**Response 503.** RETRYABLE_CONFLICT or SETTLEMENT_PENDING. Nothing was lost: retry with the same Idempotency-Key.

> **Read the settlement.** A 200 with status true is settled. A client that declares async_complete gets 202 with data.settlement_status pending while the reward is paid: poll the completion status. Confirm the reward with a signed webhook before you grant anything permanent in your own app.

## Check a completion

### `GET /platform/quests/{questId}/completion`

Where 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 | Required | Description |
| --- | --- | --- | --- | --- |
| questId | path | integer | yes | Quest ID. |
| X-AdQuest-Participant-Token | header | string | yes | 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. |

```bash
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"
```

**Response 200.** The attempt's state. settlement_status is success, pending, failed or none.

```json
{
  "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

### `GET /platform/quests/{questId}/stats`

Returns engagement counts for one quest on your platform.

**Authentication:** Public API key (X-AdQuest-Platform-Key).

| Parameter | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| questId | path | integer | yes | Quest ID. |
| X-AdQuest-Participant-Token | header | string | no | The participant token. Optional here. It adds per-user state such as completed. |

```bash
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"
```

**Response 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.

```json
{
  "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
  }
}
```

**Response 404.** QUEST_NOT_FOUND. The quest does not exist or is not available.

## Check a manual review

### `GET /platform/quests/{questId}/review`

Where 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 | Required | Description |
| --- | --- | --- | --- | --- |
| questId | path | integer | yes | Quest ID. |
| X-AdQuest-Participant-Token | header | string | yes | 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. |

```bash
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"
```

**Response 200.** The latest review for the participant. settlement_status is pending or settled once approved, otherwise null.

```json
{
  "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

### `GET /platform/quests/{questId}/execution`

State 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 | Required | Description |
| --- | --- | --- | --- | --- |
| questId | path | integer | yes | Quest ID. |
| X-AdQuest-Participant-Token | header | string | yes | 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. |

```bash
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"
```

**Response 200.** The execution state.

```json
{
  "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

### `GET /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 | Required | Description |
| --- | --- | --- | --- | --- |
| questId | path | integer | yes | Quest ID. |
| key | path | string | yes | Step key. |
| X-AdQuest-Participant-Token | header | string | yes | 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. |

```bash
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"
```

**Response 200.** The execution state.

```json
{
  "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

### `POST /platform/quests/{questId}/steps/{key}/evidence`

Ask 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 | Required | Description |
| --- | --- | --- | --- | --- |
| questId | path | integer | yes | Quest ID. |
| key | path | string | yes | Step key. |
| X-AdQuest-Participant-Token | header | string | yes | 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 | no | start begins a timed (video/banner) step; click records the click of a visit step. Omit to submit evidence. |
| evidence | body | string | no | Proof text for a manual_review step (max 2000 characters). |
| evidence_type | body | string | no | Evidence type the step expects (must match the step configuration). |
| answers | body | array | no | Survey answers: [{question_id, user_input}]. |

```bash
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 '{  }'
```

**Response 200.** The execution state.

```json
{
  "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
  }
}
```

**Response 202.** Evidence accepted for asynchronous review.

**Response 409.** STEP_OUT_OF_ORDER, STEP_NOT_STARTED, RESERVATION_EXPIRED, NOT_STARTED or QUEST_PROCESSING.

**Response 422.** The server could not verify the step from the evidence (CLICK_REQUIRED, TIMER_NOT_FINISHED, CUSTOM_EVIDENCE_MISSING, ...).
