Multi-step quests

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.

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 API answers 404 MULTI_STEP_DISABLED and the quest is not served.
• The quest belongs to your own platform and is active. Steps that depend on your own data (condition, custom, streak) work on 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.
• Your Event signing secret, if any step is proven by your backend. It stays 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.

What happens to a participant#

• 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 (count 2 distinct orders) and a profile step called profile. Follow the numbers.

1. 1

   Register the activity once per platform (setup, not per participant).

2. 2

   Start the quest and read the execution. You need execution_id and steps_version from it.

3. 3

   When your backend sees an order, send a signed event for the orders step.

4. 4

   Read the execution again to show progress. Repeat until the step says verified.

5. 5

   The profile step unlocks. Once it is verified, AdQuest settles the quest.

curl -X POST https://api.adquest.batriders.ir/api/v1/platforms/PLATFORM_ID/event-definitions \
  -H "Authorization: Bearer YOUR_DASHBOARD_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name":"order_placed","label":"Order placed","has_entity":true,"has_amount":false}'

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

curl "https://api.adquest.batriders.ir/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"]}'

import { createHmac } from "node:crypto";

// executionId and stepsVersion come from the execution you just read.
const timestamp = String(Math.floor(Date.now() / 1000));
const signature = createHmac("sha256", eventSigningSecret)
  .update(["v3", eventId, "order_placed", "23", externalUserId, timestamp, "orders", String(stepsVersion), String(executionId), orderId, "", "", ""].join("."))
  .digest("hex");

await questRequest(config, 23, "events", {
  event_id: eventId, event_name: "order_placed", source: "server", timestamp, signature,
  step_key: "orders", entity_id: orderId,
});

The response for an accepted event says whether it counted. A duplicate delivery returns the same result and does not count twice.

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

Condition steps in detail#

A condition step reads: metric of an activity, operator, target. For example, count of order_placed is at least 3.

• Operators: gte, gt, eq, lte, lt. There are no expressions and no AND/OR inside one step. Use two steps for two conditions.
• Register every activity first (the call in the walkthrough). An unregistered event_name is refused with EVENT_NOT_REGISTERED.
• Only activity that happens after the participant starts counts. In a sequential quest, only after that step unlocks.
• Late events are accepted for up to 7 days, in any order. An event more than 60 seconds in the future is refused.
• Amounts are integers in minor units (cents). 5000 with currency USD is 50.00 USD.

Condition events need the v3 signature. It is the v2 signature plus four fields: entity_id, amount_minor, currency and reverses_event_id. Use an empty string for any field the event does not have, as in the walkthrough.

const canonical = [
  "v3", eventId, eventName, String(questId), externalUserId, timestamp,
  stepKey, String(stepsVersion), String(executionId),
  entityId, amountMinor, currency, reversesEventId, // "" when the event has none
].join(".");
// signature = lowercase hex HMAC-SHA256(canonical) with your Event signing secret

curl -X POST https://api.adquest.batriders.ir/api/v1/platforms/PLATFORM_ID/event-definitions \
  -H "Authorization: Bearer YOUR_DASHBOARD_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name":"order_refunded","label":"Order refunded","has_entity":true,"reverses":"order_placed"}'

• Send the refund to the same step with event_name order_refunded and reverses_event_id set to the original event_id.
• The original event 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.

SDK calls you will use#

Errors and what to do#

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 participant starts a fresh attempt.

In the dashboard, the integration panel shows when each step last received a verified event from your backend, and a Test callback button sends one signed request to your url_callback endpoint so you can see whether it answers.

Mistakes people make#

• Signing in the browser. The signing secret belongs on your backend only.
• Using the event id of a quest-level event for a step. Each step event needs its own event_id and step_key.
• Signing a v2 string for a condition event. Condition steps need the v3 string, with empty fields kept as empty strings.
• 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#