# Multi-step quests

> A participant finishes several steps and is paid once. What your app sends, what AdQuest decides, and how to read progress.

Source: https://dashboard.adquest.io/docs/multi-step-quests · Audience: Developers · Section: Build

## The picture in one minute

A multi-step quest is one quest with a checklist. The participant ticks off the steps, and AdQuest pays one reward after the last required step is verified. Think of it as a boarding pass: each stamp is a step, and the reward is the flight.

| Idea | What it means for you |
| --- | --- |
| One reward | The quest pays once. A step never pays, so you never grant anything per step. |
| The server decides | Your app can say "start" or "click". It can never say "done". AdQuest marks a step verified. |
| Each participant has an execution | Their personal run of the quest. It records which steps are verified and which steps are still open. |
| Steps have a version | If the owner edits the steps, new participants get the new version. People already running keep the old one. |

> **Who proves what.** Three parties can prove a step: your server (by reporting activities or answering a URL callback), AdQuest itself, or a reviewer. The next section says which proves which step.

## Before you start

- Participant sessions working, so you have a participant token for each user. See the participant sessions guide.
- Multi-step quests are enabled for your environment. If they are not, the step routes answer MULTI_STEP_DISABLED (404, or 503 when attempt holds are off) and the quest is not served.
- The quest belongs to your own platform and is active. Multi-step quests are private quests only.
- Your client declares the multi_step capability. The AdQuest SDK does this for you. A raw HTTP client must send the X-AdQuest-Runtime header shown below, or the quest is hidden from it and start answers 404 QUEST_NOT_FOUND.
- Your Secret Key, if your server reports activities, and your Event signing secret if a step uses a URL callback. Both stay on your server.

## Who proves each step?

Find the step in the left column. The other columns say who proves it and what you have to build.

| Step type | Participant does | Proven by | You build |
| --- | --- | --- | --- |
| condition | Reaches a target, such as 3 orders, 5000 spent or a verified account | Your server | Report the step’s activity |
| custom → url_callback | Does something your system can confirm | Your server | An HTTPS endpoint that answers verified: true |
| custom → manual_review | Submits proof | A reviewer | Nothing. Staff approve or reject. |
| streak | Returns on consecutive days | Your server | Report the step’s daily activity |
| video, banner, survey, visit | Watches, reads, answers or visits | AdQuest | Call start, click or send answers. AdQuest measures time on its own. |
| profile, referral | Saves a profile or invites a friend | AdQuest | As for a single quest: a fresh session with the profile, or a reported signup |

> **Rule of thumb.** If the action has value to you (an order, a deposit), have your server prove it: report it for a condition step, or answer a url_callback. If it is about attention, let AdQuest measure it. If it is a judgement call, use manual_review.

## What happens to a participant

| Stage | What happens | Step status |
| --- | --- | --- |
| 1. Start | AdQuest reserves a slot and the budget, and binds the steps version to the participant. | All steps pending |
| 2. Steps | Each step moves on its own as proof arrives. | pending → verified (instant proof), pending → in_review → verified (a reviewer decides), in_review → rejected → in_review (resubmit, limited attempts) |
| 3. Admission | Every required step is verified. AdQuest admits the execution. | steps_complete is true |
| 4. Settlement | The reward is paid once. | settlement_status: pending → success |

- A verified step stays verified. Sending proof for it again changes nothing and answers 200.
- Sequential quests unlock a step only after every required step before it is verified. Unordered quests unlock all steps at once.
- An optional step never blocks the reward.
- Approval does not need the participant to be online. If a reviewer approves late, AdQuest takes a new hold under the same capacity and budget rules, and retries every minute if the quest is paused or full. Nothing is paid without a hold.

## Walkthrough: place 2 orders, then verify your profile

This example uses a sequential quest with two steps: a condition step called orders (2 different orders) and a profile step called profile. Follow the numbers.

1. The publisher registers the activity order_placed, carrying an item id, once per platform. The quest’s orders step counts it.
2. Start the quest and read the execution.
3. When your server sees an order, report it as an activity. You do not name the quest or the step.
4. Read the execution again to show progress. Repeat until the step says verified.
5. The profile step unlocks. Once it is verified, AdQuest settles the quest.

- [Register activities](https://dashboard.adquest.io/docs/dashboard/activities): For publishers: add order_placed with an item id.

**2. Start and read the execution (what the SDK client does)**

```typescript
import { createAdQuestClient } from "@adquest/sdk";

const client = createAdQuestClient({ baseUrl, apiKey, participantToken, externalUserId });
await client.startQuest(23, { requiresTimer: false });
const execution = await client.getQuestExecution(23);
// execution.execution_id, execution.steps_version, execution.steps[].status
```

**2. The same read over HTTP**

```bash
curl "https://api.adquest.io/api/v1/platform/quests/23/execution?external_user_id=user_123" \
  -H "X-AdQuest-Platform-Key: YOUR_PUBLIC_API_KEY" \
  -H "X-AdQuest-Participant-Token: TOKEN_FOR_THIS_USER" \
  -H 'X-AdQuest-Runtime: {"runtime_version":1,"capabilities":["multi_step"]}'
```

**3. Your server reports one order — using reportActivities from Report activities**

```typescript
await reportActivities([
  { id: "order_" + orderId, type: "order_placed", user: externalUserId, occurred_at: Math.floor(Date.now() / 1000), entity_id: orderId },
]);
```

Each fact is answered accepted or duplicate. A duplicate does not count twice.

**4. What the execution looks like mid-way**

```json
{
  "quest_id": 23,
  "execution_id": 812,
  "steps_version": 2,
  "ordering": "sequential",
  "state": "reserved",
  "expires_at": "2026-11-09T15:30:00+00:00",
  "steps": [
    { "step_key": "orders", "format": "condition", "status": "pending", "available": true,
      "progress": { "current": 1, "target": 2, "unit": "items", "satisfied": false } },
    { "step_key": "profile", "format": "profile", "status": "pending", "available": false }
  ],
  "steps_complete": false,
  "settlement_status": "none"
}
```

> **Show progress from the execution.** Draw your progress bar from steps[].progress and steps[].status. Do not keep your own counter. The server recomputes it, and a refund can lower it.

## Condition steps in detail

A condition step reads: metric of an activity, operator, target. For example, count of order_placed is at least 3. Your server reports the activity as usual; AdQuest counts the facts that arrive after the step unlocks.

| Metric | Counts | Each fact must carry |
| --- | --- | --- |
| occurrence | Whether it happened once | Nothing extra |
| count | Number of facts | Nothing extra |
| count_distinct | Different entity_id values, so one order counts once even if reported twice | entity_id (the activity carries an item id) |
| sum | Total of amount_minor, in one currency | amount_minor as an integer in minor units, and currency (the activity carries an amount) |
| state | A state fact equal to the step’s state, such as verified, reached after the step unlocks | state, with occurred_at = when it was reached (a state activity) |

- Operators: gte, gt, eq, lte, lt. A state step always uses eq. There are no expressions and no AND/OR inside one step. Use two steps for two conditions.
- The activity must be registered before the step is published. An unregistered one is refused with EVENT_NOT_REGISTERED.
- Only activity after the participant starts counts. In a sequential quest, only after that step unlocks.
- Facts may arrive late and in any order, up to 7 days after they happened. A fact more than 60 seconds in the future is refused.
- Amounts are integers in minor units (cents). 5000 with currency USD is 50.00 USD.

A refund is its own activity, registered as reversing order_placed. Report it with reverses set to the id of the original fact.

**Report a refund — using reportActivities from Report activities**

```typescript
await reportActivities([
  { id: "refund_" + orderId, type: "order_refunded", user: externalUserId, occurred_at: Math.floor(Date.now() / 1000), entity_id: orderId, reverses: "order_" + orderId },
]);
```

- The original fact stops counting. This works even if the refund arrives before the original.
- Before the quest is admitted, a refund can move a verified step back to pending. After admission, a refund changes nothing and the reward is not taken back.

## Reading the state

Poll the execution, or read one step. Use these fields to drive your screen.

| Field | Use it to |
| --- | --- |
| steps[].status | Show pending, in_review, verified or rejected. |
| steps[].available | Grey out locked steps in a sequential quest. |
| steps[].progress | Show "2 / 3 items" for a condition step. |
| steps[].elapsed_seconds | Resume a video or timer countdown after the widget reopens. The server measures it. |
| steps[].review | Explain a rejection and whether the participant may resubmit. |
| state and expires_at | Show how long the reservation is held. |
| steps_complete | True when every required step is verified. |
| settlement_status | none, pending or success. Credit your own app only on success. |
| unsettled_reason | Why a complete execution is not paid yet, such as a paused quest. AdQuest keeps retrying. |

> **Warning: Never grant a reward on steps_complete.** steps_complete means every step is verified. The payment happens after that. Wait for settlement_status success or the quest.completed webhook.

## SDK calls you will use

| Goal | SDK method |
| --- | --- |
| Start the quest | startQuest(questId) |
| Read all steps | getQuestExecution(questId) |
| Read one step | getQuestStep(questId, stepKey) |
| Start, click, answer or send proof for a step | submitQuestStepEvidence(questId, stepKey, input) |
| Finish the quest | A state read. It returns 409 MULTI_STEP_REQUIRED until the required steps are verified. It never verifies anything. |

## Errors and what to do

| Code | Meaning | What to do |
| --- | --- | --- |
| MULTI_STEP_DISABLED | Multi-step quests are off for the environment (404), or attempt holds are off (503) | Ask AdQuest to enable it |
| QUEST_NOT_FOUND | On start or complete: the client did not declare multi_step, or the quest is not available | Send the runtime header |
| NOT_STARTED | The participant has no execution | Start the quest first |
| STEP_NOT_FOUND | step_key is not in the participant's version | Read the execution and use its keys |
| STEP_OUT_OF_ORDER | An earlier required step is not verified yet | Show the step as locked until available is true |
| STEP_NOT_STARTED | A timed step was submitted before start | Send action start, wait, then submit |
| MULTI_STEP_REQUIRED | Complete was called too early | Keep showing the steps. Do not retry in a loop. |
| EVENT_NOT_REGISTERED | The step’s activity is not registered for the platform | Register it, then publish the step |
| STEP_CALLBACK_ONLY | You sent evidence to a streak step | Streak steps move only from the daily activity your server reports |
| TIMING_ADMIN_ONLY | An owner set answer, gap or attempt time on a type that does not allow it | Only custom and multi-step quests accept an owner attempt time (15 minutes to 30 days). Leave timing to AdQuest elsewhere |
| RESERVATION_EXPIRED, QUEST_PROCESSING, QUEST_ALREADY_COMPLETED | The hold ended, is settling or is already paid | Read the execution and show the real state |
| ATTEMPTS_EXHAUSTED | Start after the participant’s only attempt ended unpaid | Show the quest as finished. A multi-step quest allows one attempt unless AdQuest changes the limit |

## Step links, attempt time and checking your integration

A step can carry a link to your app (https or an app scheme such as myapp://orders). The SDK only opens it; your app still has to prove the step. Read it as config.action_url and config.action_label on the step.

Multi-step and custom quests can have an attempt time of 15 minutes to 30 days. Leave it empty for no deadline. After it passes, late evidence is refused and the attempt ends. A multi-step quest allows one attempt unless AdQuest raises the limit, so a new start then answers 409 ATTEMPTS_EXHAUSTED.

A url_callback check for a step also names step_key, execution_id and steps_version, signed the same way as for a custom quest. The publisher’s Activities page shows whether your server’s facts are arriving.

- [URL callback](https://dashboard.adquest.io/docs/quest-evidence/custom#callback): The signed request and the answer AdQuest expects.

## Mistakes people make

- Reporting activities from the browser. The Secret Key belongs on your server only.
- Reporting a fact before it is final, such as an unconfirmed deposit.
- Counting progress yourself. Read it from the execution.
- Treating complete as proof. It cannot verify a step.
- Forgetting the runtime header on raw HTTP. The quest then looks missing.
- Editing steps and expecting running participants to change. They keep their version; only new participants get the new steps.

## Next steps

- [Multi-step evidence](https://dashboard.adquest.io/docs/quest-evidence/multi-step): The evidence each step type accepts, in one page.
- [Report activities](https://dashboard.adquest.io/docs/quest-evidence/activities): The signed call condition and streak steps count.
- [Quest methods](https://dashboard.adquest.io/docs/sdk/quests): Every SDK method, including the step calls.
- [Webhooks](https://dashboard.adquest.io/docs/webhooks): Get quest.completed when the reward is paid.
- [Set up this quest in the dashboard](https://dashboard.adquest.io/docs/dashboard/quests/multi-step): For publishers: add and order the steps.
