Skip to documentation
AdQuestDocs

Report activities

Your server reports what users did, once, in one signed call. AdQuest works out which quests that completes and pays.

On this page

What you do

  1. Agree the activity names with the publisher, who registers each one for your platform (its name, and whether it carries an amount, an item id or a state).

  2. Report every relevant fact from your server, once, as it happens: POST /server/activities with your Secret Key.

  3. Answer each payout: when AdQuest sends fulfillment.requested, deliver the reward and acknowledge it, or reject it.

You never name a quest and never send a participant token. Each quest says which activity it counts and how. When a participant’s facts meet a quest’s goal, AdQuest settles it at once. There is no Claim button.

Report activities

Send X-AdQuest-Platform-Key with X-AdQuest-Platform-Secret (your Secret Key) from your server. Signing the body with X-AdQuest-Signature and your Event signing secret is an optional alternative to the Secret Key. Up to 500 facts and 512 KB per request. The route answers only once activities are enabled for your environment. The helper below is used by every server example in these docs.

Server request (Node.js, server only)
export async function serverRequest(method: "GET" | "POST", path: string, body?: unknown) {
  const response = await fetch(process.env.ADQUEST_API_URL + path, {
    method,
    headers: {
      "Content-Type": "application/json",
      "X-AdQuest-Platform-Key": process.env.NEXT_PUBLIC_ADQUEST_PLATFORM_API_KEY!,
      "X-AdQuest-Platform-Secret": process.env.ADQUEST_PLATFORM_SECRET!,
    },
    body: body === undefined ? undefined : JSON.stringify(body),
  });
  return response.json();
}

export const reportActivities = (activities: Record<string, unknown>[]) =>
  serverRequest("POST", "/server/activities", { activities });
One fact of each kind
await reportActivities([
  // An event: something happened. entity_id only when the activity carries an item id.
  { id: "trd_9f31", type: "trade.completed", user: "user_123", occurred_at: 1763459990, entity_id: "BTC-IRR" },
  // An amount: an integer in minor units, in the activity's currency.
  { id: "dep_8812", type: "deposit.completed", user: "user_123", occurred_at: 1763459995, amount_minor: "2000000", currency: "IRR" },
  // A state: the value reached, and when the user reached it on your side.
  { id: "kyc_441", type: "kyc.verified", user: "user_123", occurred_at: 1763459000, state: "verified" },
  // A signup: the inviter's code, read from ?adquest_ref= on the invite link.
  { id: "su_77", type: "user.signed_up", user: "user_456", occurred_at: 1763460000, referral_code: "ABC123XYZ0" },
]);
FieldRequiredMeaning
idYesYour unique id for this fact: up to 128 letters, digits, _ . : or -. Sending it again is safe.
typeYesA registered activity name, such as deposit.completed.
userYesYour user id: the external_user_id you use for participant sessions, up to 255 characters.
occurred_atYesUnix seconds when it happened on your side. For a state: when the user reached it.
amount_minor, currencyWhen the activity carries an amountAn integer in minor units (cents) as a string, and the registered currency.
entity_idWhen the activity carries an item idWhat the fact is about: an order, a market, a product.
stateFor a state activityThe value reached, such as verified: up to 64 letters, digits, _ . or -.
referral_codeFor a signup that came from an inviteThe inviter’s code: up to 32 letters and digits.
reversesFor a reversal activityThe id of the fact it cancels, such as a refunded order. Same format as id.

Read the answer

Each fact is answered on its own, in order, in data.results. accepted means it is stored. duplicate means that id was already stored: nothing changes. Resend only the facts whose result has retryable: true.

Response
{
  "status": true,
  "code": "OK",
  "message": "Activities received",
  "data": {
    "results": [
      { "id": "trd_9f31", "status": "accepted" },
      { "id": "dep_8812", "status": "duplicate" },
      { "id": "kyc_441", "status": "rejected", "code": "UNKNOWN_ACTIVITY_TYPE" }
    ]
  }
}
CodeWhat to fix
UNKNOWN_ACTIVITY_TYPEThe type is not registered for your platform.
INVALID_ACTIVITYid or user is missing or too long, id has a character other than letters, digits, _ . : or -, or the fact sends a field its activity does not take (a state on an event).
ID_REUSEDThe same id was sent before with a different body. Use a new id for a new fact.
INVALID_OCCURRED_AT, OCCURRED_AT_OUT_OF_RANGEoccurred_at is not Unix seconds, is more than 60 seconds in the future, or an event is older than 7 days.
INVALID_AMOUNT, CURRENCY_MISMATCHThe amount is missing or not an integer, or the currency is not the registered one.
ENTITY_ID_REQUIREDThe activity carries an item id and the fact has none.
STATE_REQUIREDA state activity was sent without a state.
INVALID_REVERSALreverses is missing on a reversal activity, or sent on another activity.
INVALID_REFERRAL_CODEreferral_code is not a valid code.
STORE_UNAVAILABLERetryable. Nothing was stored. Resend the batch.

A whole request can fail too: 401 SERVER_AUTH_REQUIRED (check the public key and the Secret Key), 401 SIGNATURE_INVALID or SIGNATURE_EXPIRED (only when you sign instead), 403 ACTIVITIES_NOT_CONFIGURED (register an activity first), 413 BATCH_TOO_LARGE, 422 INVALID_BODY, and 503 ACTIVITY_CONFIG_UNAVAILABLE (retryable: nothing was stored, resend shortly).

What counts

  • Only facts after the quest starts for a participant count: when they press Start, or when the quest went live for a quest that includes everyone. Earlier work never pays.
  • Send a fact once it is final: a deposit when it is confirmed, not when it is submitted. A reward that has been paid is never taken back.
  • A reversal (such as a refund) cancels the fact it names. Before the quest settles, progress goes back down.
  • A state is reached at its occurred_at. A user verified before the quest started is not credited, so send the real time, not the time you send it.

Answer payouts

When a reward is yours to deliver, AdQuest sends the fulfillment.requested webhook. Deliver it, then acknowledge it with your own reference. If your review refuses it, reject it with a reason code (lowercase letters, digits and _). Nothing returns to the quest’s budget, because a reward you deliver moved no AdQuest money; the participant’s history shows it as rejected. Both answers are final. Repeating the same answer is safe; a different one returns 409 FULFILLMENT_CONFLICT.

Acknowledge or reject
// After you delivered the reward:
await serverRequest("POST", "/server/fulfillments/12/acknowledge", { external_reference: "payout_7781" });
// Or, when your review refuses it:
await serverRequest("POST", "/server/fulfillments/13/reject", { reason_code: "account_closed" });

Other server calls (optional)

CallReturns
GET /server/questsYour platform’s quests: status, schedule, budget and the activity rules they count. type is the format key, except market_research for surveys.
GET /server/fulfillmentsPayouts, filtered by status and created_from / created_to.
GET /server/reconciliation?from=&to=Per UTC day and asset: how many rewards were requested, acknowledged, rejected or still pending, and their totals. Up to 93 days.
GET /server/activities/{id}What AdQuest stored for one fact.
POST /server/referral-codesRegisters your own invite codes, for referral quests that use Platform codes. See Referral evidence, Use your own invite codes.

Lists return data.data and data.next. Pass next as after to read the next page, with limit up to 200. These calls take your Secret Key as X-AdQuest-Platform-Secret, or the same signature (of an empty body for a GET).

Next steps

Something unclear, missing or wrong here? Tell us