Quest evidence
Quest evidence overview
What each quest format needs before AdQuest pays: evidence from the widget, or facts your server reports.
On this page
Prerequisites
- A working integration: participant sessions and a widget or client.
- A quest in the format you want, created in the dashboard and active.
- The public API key, API URL and the user’s participant token.
- For event, referral and streak quests: your Secret Key, kept on your server. Signing with the Event signing secret is an optional alternative.
How completion works
AdQuest decides every completion on its servers. Formats played in the widget send their evidence from the participant’s session. Formats proven by your product (event, referral, streak) need one thing from you: your server reports activities, and AdQuest settles them by itself.
| Format (API type) | You send | Then |
|---|---|---|
| Video (video) | start, then watch progress, then one answer per question; a first miss is asked again at the end | The last right answer completes it. A second miss rejects it. |
| Time-link (banner) | start, the timer, an optional click, then one answer per question; a first miss is asked again at the end | The last right answer completes it. A second miss rejects it. |
| Survey (survey) | start without a timer, then the answers | complete |
| Quiz (quiz) | start without a timer, then one answer per question; a first miss is asked again at the end | The last right answer completes it. A second miss rejects it. |
| Visit destination (visit) | start, then the visit | complete |
| Reach a target (event) | Nothing from the widget. Your server reports the activity. | Settled by AdQuest when the goal is met |
| Profile (profile) | the saved profile in a new participant session | complete |
| Referral (referral) | Your server reports the friend’s signup with the inviter’s code. | Settled by AdQuest when the minimum is met |
| Streak (streak) | Your server reports the daily activity. | Settled by AdQuest on the last day |
| Custom (custom) | complete, then AdQuest checks your URL, or a reviewer checks the evidence | Settled when verified or approved |
| Multi-step (multi_step) | evidence for each step, or the activity a step counts | Settled after every required step is verified |
The request helper
Authenticated public API helper
type ApiConfig = { baseUrl: string; apiKey: string; participantToken: string; externalUserId: string; deliveryToken?: string };
export async function questRequest(config: ApiConfig, questId: number, action: string, body: Record<string, unknown> = {}) {
const response = await fetch(config.baseUrl.replace(/[/]$/, "") + "/platform/quests/" + questId + "/" + action, {
method: "POST",
headers: {
"Content-Type": "application/json",
"X-AdQuest-Platform-Key": config.apiKey,
"X-AdQuest-Participant-Token": config.participantToken,
},
body: JSON.stringify({ delivery_token: config.deliveryToken, ...body, external_user_id: config.externalUserId }),
});
const result = await response.json();
if (!response.ok || !result.status) throw new Error(result.message || "Quest request failed");
return result.data;
}One page per format
Report activitiesThe one signed call your server makes for event, referral and streak quests.Video evidenceProgress evidence and the question.Time-link / banner evidenceTimer, click and question.Survey evidenceSeveral questions, no timer.Quiz evidenceGraded questions, one at a time.Visit evidenceAttribute a visit.Reach a target evidenceA goal on an activity your server reports.Profile evidenceSend the saved profile.Referral evidenceReport signups with the inviter’s code.Streak evidenceA day counts when your server reports it.Custom evidenceA URL callback or a manual review.Multi-step evidenceEvidence per step, one reward.Multi-step quests guideStart here if multi-step feels complicated.