Skip to documentation
AdQuestDocs

Server routes API

Routes your backend calls: report activities, acknowledge or reject payouts, register your own referral codes, read quests and reconciliation, and send winner contact.

On this page

Signing

Every /server route takes X-AdQuest-Platform-Key with your Secret Key as X-AdQuest-Platform-Secret. If you prefer to sign instead, send X-AdQuest-Signature: t=<unix seconds>,v1=<hex HMAC-SHA256 of t + "." + raw body> with your Event signing secret; a signature more than 5 minutes old is refused.

Post a winner’s contact

POST/platform/lottery-claims/{claimId}/contact

Sends AdQuest the winner’s email after a lottery.winner webhook, so AdQuest can notify them. Call it only for the winner of that claim. A platform that tells its winners itself (notifies_lottery_winners on the platform) does not need it: the lottery.winner webhook carries lottery_name, award_name, award_type, award_description, claim_expires_at and claim_screen (claims: the SDK screen where the winner registers the prize, opened with the widget's navigate or the embed's adquest:init / adquest:navigate view), and AdQuest sends no email; there email and display_name are optional, and an email sent anyway is still mailed.

Authentication: Secret Key, sent as the X-AdQuest-Platform-Secret header. Backend only.

ParameterInTypeDescription
claimId requiredpathintegerClaim ID from the lottery.winner webhook.
external_user_id requiredbodystringYour ID for the winner. Max 255 characters.
emailbodystringThe winner’s email. Max 255 characters. Required unless your platform notifies its winners itself.
display_namebodystringThe winner’s name. Max 255 characters.
Request, cURL
curl -X POST https://api.adquest.io/api/v1/platform/lottery-claims/91/contact \
  -H "Content-Type: application/json" \
  -H "X-AdQuest-Platform-Secret: YOUR_SECRET_KEY" \
  -d '{
  "external_user_id": "player-42",
  "email": "ada@example.com",
  "display_name": "Ada"
}'

200 The contact was received.

Response 200
{
  "status": true,
  "code": "OK",
  "message": "Winner contact received",
  "data": {
    "claim_id": 91,
    "notified": true
  }
}

401 The Secret Key is missing or wrong.

403 The platform is not accepted and active.

404 CLAIM_NOT_AVAILABLE.

429 RATE_LIMITED. Too many contact requests.

Report activities

POST/server/activities

Reports facts from your server once, as they happen: trades, deposits, KYC, signups. Do not name quests: AdQuest works out which quests each fact completes and settles them. Up to 500 items and 512 KB per request. Send your Secret Key as X-AdQuest-Platform-Secret; signing with X-AdQuest-Signature is an optional alternative. Served by the serving plane, and only once activities are enabled for the environment (otherwise the route does not exist). Each item is answered on its own, so retry only the items whose result is retryable.

Authentication: Secret Key, sent as the X-AdQuest-Platform-Secret header. Backend only.

ParameterInTypeDescription
activities requiredbodyarrayThe facts, at most 500.
Request, cURL
curl -X POST https://api.adquest.io/api/v1/server/activities \
  -H "Content-Type: application/json" \
  -H "X-AdQuest-Platform-Secret: YOUR_SECRET_KEY" \
  -H "X-AdQuest-Platform-Key: YOUR_PUBLIC_API_KEY" \
  -d '{ "activities": [{"id":"trd_9f31","type":"trade.completed","user":"user_123","occurred_at":1763459990,"entity_id":"BTC-IRR"}] }'

200 data.results has one entry per item, in order: status accepted, duplicate or rejected (with code and retryable).

Response 200
{
  "status": true,
  "code": "OK",
  "message": "Activities received",
  "data": {
    "results": [
      {
        "id": "trd_9f31",
        "status": "accepted"
      },
      {
        "id": "trd_9f30",
        "status": "duplicate"
      },
      {
        "id": "x_1",
        "status": "rejected",
        "code": "UNKNOWN_ACTIVITY_TYPE"
      }
    ]
  }
}

401 SERVER_AUTH_REQUIRED (wrong public key or Secret Key), or SIGNATURE_INVALID / SIGNATURE_EXPIRED when you sign instead (more than 5 minutes off).

403 ACTIVITIES_NOT_CONFIGURED: no activity is registered for your platform yet.

413 BATCH_TOO_LARGE: more than 500 items or 512 KB.

422 INVALID_BODY: the body is not {"activities": [...]} with at least one item.

503 ACTIVITY_CONFIG_UNAVAILABLE: retryable, nothing was stored. Resend the batch shortly.

Acknowledge a fulfillment

POST/server/fulfillments/{id}/acknowledge

You delivered the reward of a fulfillment.requested webhook. Final: it can no longer be rejected. Repeating the same external_reference is safe. On a referral quest the webhook payload carries referral_role (inviter | invitee): one fulfillment per rewarded side, and with pay_each_invite one per invite for the inviter (with referral_payout_id and unit_no). The payload amount is a whole number for AdQuest tokens and the exact decimal string ("0.25") for a reward in your own unit. If the activity that earned an unpaid reward is reversed (an activity with `reverses`), AdQuest cancels it and sends fulfillment.canceled (fulfillment_id, reason_code activity_reversed, amount, asset, quest_id, external_user_id, referral_role) to every webhook that receives fulfillment.requested; acknowledging or rejecting it then answers 409 FULFILLMENT_CONFLICT. An acknowledged reward is never canceled.

Authentication: Secret Key, sent as the X-AdQuest-Platform-Secret header. Backend only.

ParameterInTypeDescription
id requiredpathintegerFulfillment ID from the fulfillment.requested webhook.
external_reference requiredbodystringYour own reference for the delivered reward.
Request, cURL
curl -X POST https://api.adquest.io/api/v1/server/fulfillments/12/acknowledge \
  -H "Content-Type: application/json" \
  -H "X-AdQuest-Platform-Secret: YOUR_SECRET_KEY" \
  -H "X-AdQuest-Platform-Key: YOUR_PUBLIC_API_KEY" \
  -d '{ "external_reference": "order-8841" }'

200 data has id, status, external_reference and rejection_reason.

Response 200
{
  "status": true,
  "code": "OK",
  "message": "Fulfillment acknowledged",
  "data": {
    "id": 12,
    "status": "acknowledged",
    "external_reference": "order-8841",
    "rejection_reason": null
  }
}

401 SERVER_AUTH_REQUIRED, SIGNATURE_INVALID or SIGNATURE_EXPIRED. Sign the request with your event signing secret, or send the platform secret.

404 FULFILLMENT_NOT_FOUND.

409 FULFILLMENT_CONFLICT: already rejected, or acknowledged with another reference.

Reject a fulfillment

POST/server/fulfillments/{id}/reject

You refused the reward after your own review. Final: it cannot be acknowledged afterwards, and an acknowledged one cannot be rejected. The participant's history shows it as rejected. Nothing returns to the quest's budget: a reward you fulfil moved no AdQuest money. A fulfillment.rejected webhook echoes it. Repeating the same reason_code is safe. A canceled fulfillment answers 409 FULFILLMENT_CONFLICT.

Authentication: Secret Key, sent as the X-AdQuest-Platform-Secret header. Backend only.

ParameterInTypeDescription
id requiredpathintegerFulfillment ID from the fulfillment.requested webhook.
reason_code requiredbodystringYour reason, lowercase letters, digits and _.
Request, cURL
curl -X POST https://api.adquest.io/api/v1/server/fulfillments/12/reject \
  -H "Content-Type: application/json" \
  -H "X-AdQuest-Platform-Secret: YOUR_SECRET_KEY" \
  -H "X-AdQuest-Platform-Key: YOUR_PUBLIC_API_KEY" \
  -d '{ "reason_code": "kyc_failed" }'

200 data has id, status (rejected) and rejection_reason.

Response 200
{
  "status": true,
  "code": "OK",
  "message": "Fulfillment rejected",
  "data": {
    "id": 12,
    "status": "rejected",
    "external_reference": null,
    "rejection_reason": "kyc_failed"
  }
}

401 SERVER_AUTH_REQUIRED, SIGNATURE_INVALID or SIGNATURE_EXPIRED. Sign the request with your event signing secret, or send the platform secret.

404 FULFILLMENT_NOT_FOUND.

409 FULFILLMENT_CONFLICT: already acknowledged, or rejected with another reason.

List fulfillments

GET/server/fulfillments

Your platform's fulfillments, newest first. amount is a whole number for AdQuest tokens and lottery prizes, and the exact decimal string ("0.5") for a reward in your own unit (USDT, TOMAN...), the same as in the webhook.

Authentication: Secret Key, sent as the X-AdQuest-Platform-Secret header. Backend only.

ParameterInTypeDescription
statusquerystringpending, delivered, acknowledged, rejected, failed or terminal_failed.
created_fromquerystringOnly fulfillments created at or after this time.
created_toquerystringOnly fulfillments created before this time.
afterquerystringThe `next` value of the previous page.
limitqueryintegerPage size, 1 to 200. Default 50.
Request, cURL
curl "https://api.adquest.io/api/v1/server/fulfillments" \
  -H "X-AdQuest-Platform-Secret: YOUR_SECRET_KEY" \
  -H "X-AdQuest-Platform-Key: YOUR_PUBLIC_API_KEY"

200 data.data has id, kind, status, amount, asset, quest_id, external_user_id, external_reference, rejection_reason and the timestamps; data.next is the next page cursor or null.

Response 200
{
  "status": true,
  "code": "OK",
  "message": "OK",
  "data": {
    "data": [
      {
        "id": 12,
        "kind": "quest_reward",
        "status": "delivered",
        "amount": 100,
        "asset": "TRX",
        "quest_id": 42,
        "external_user_id": "user_123",
        "external_reference": null,
        "rejection_reason": null,
        "created_at": "2026-11-18T10:00:00+00:00",
        "acknowledged_at": null,
        "rejected_at": null
      }
    ],
    "next": null
  }
}

401 SERVER_AUTH_REQUIRED, SIGNATURE_INVALID or SIGNATURE_EXPIRED. Sign the request with your event signing secret, or send the platform secret.

List quests

GET/server/quests

Your platform's quests with status, dates, budget and the activity rules each one counts. Referral quests also carry `referral` (reward_target inviter|invitee|both, pay_each_invite, min_attributions, code_source, activity_type, qualify_activity_type (null when the signup alone counts), and inviter_amount / invitee_amount: what one unit pays each side, as decimals; each side's fulfillment carries its own amount); null on other types. `reward` is what one unit pays (one completion, or one invite on a per-invite referral): amount, unit, caps and whether the platform pays it (paid_by_platform).

Authentication: Secret Key, sent as the X-AdQuest-Platform-Secret header. Backend only.

ParameterInTypeDescription
updated_sincequerystringOnly quests changed at or after this time.
afterquerystringThe `next` value of the previous page.
limitqueryintegerPage size, 1 to 200. Default 50.
Request, cURL
curl "https://api.adquest.io/api/v1/server/quests" \
  -H "X-AdQuest-Platform-Secret: YOUR_SECRET_KEY" \
  -H "X-AdQuest-Platform-Key: YOUR_PUBLIC_API_KEY"

200 data.data has id, title, type, status, starts_at, ends_at, token_reward, token_reward_total, reward_is_max, reward_unit, asset, budget, settled_completions, activity_rules and updated_at; data.next is the next page cursor or null. type is the stored type name, which is the format key except for surveys (market_research). token_reward is what the participant receives and token_reward_total the gross, both for the whole quest (for per-unit rewards the full amount; reward_is_max marks an up-to amount). reward_unit is your own unit ({code, label, icon_url}) or null for AdQuest tokens; asset is the value fulfillment.requested carries for this quest (the unit code, or ADQ_TOKEN).

Response 200
{
  "status": true,
  "code": "OK",
  "message": "OK",
  "data": {
    "data": [
      {
        "id": 42,
        "title": "Make 3 trades",
        "type": "event",
        "status": "active",
        "starts_at": "2026-11-18T00:00:00+00:00",
        "ends_at": "2026-11-30T23:59:59+00:00",
        "token_reward": 10,
        "token_reward_total": 10,
        "reward_is_max": false,
        "reward_unit": {
          "code": "DKC",
          "label": "Coins",
          "icon_url": null
        },
        "asset": "DKC",
        "budget": "1000000.00",
        "settled_completions": 17,
        "activity_rules": [
          {
            "format": "event",
            "activity_type": "trade.completed",
            "metric": "count",
            "operator": "gte",
            "target": 3,
            "enrollment": "auto",
            "live_from": 1763424000,
            "live_until": 1764547199
          }
        ],
        "reward": {
          "amount": "10",
          "unit": "USDT",
          "unit_label": "Tether",
          "metric": "completion",
          "max_units": null,
          "max_amount": null,
          "paid_by_platform": true
        },
        "referral": null,
        "updated_at": "2026-11-18T09:00:00+00:00"
      }
    ],
    "next": null
  }
}

401 SERVER_AUTH_REQUIRED, SIGNATURE_INVALID or SIGNATURE_EXPIRED. Sign the request with your event signing secret, or send the platform secret.

Reconciliation

GET/server/reconciliation

Per UTC day and asset: how many rewards were requested and how many (and how much) are in each state. At most 93 days. Amounts of your own units are exact decimal strings; AdQuest tokens are whole numbers.

Authentication: Secret Key, sent as the X-AdQuest-Platform-Secret header. Backend only.

ParameterInTypeDescription
from requiredquerystringFirst UTC day, inclusive.
to requiredquerystringExclusive.
Request, cURL
curl "https://api.adquest.io/api/v1/server/reconciliation?from=2026-11-01&to=2026-11-08" \
  -H "X-AdQuest-Platform-Secret: YOUR_SECRET_KEY" \
  -H "X-AdQuest-Platform-Key: YOUR_PUBLIC_API_KEY"

200 data.days has one entry per day and asset with requested and per-status count and amount.

Response 200
{
  "status": true,
  "code": "OK",
  "message": "Reconciliation",
  "data": {
    "from": "2026-11-17",
    "to": "2026-11-18",
    "days": [
      {
        "day": "2026-11-17",
        "asset": "TRX",
        "requested": {
          "count": 3,
          "amount": 300
        },
        "acknowledged": {
          "count": 2,
          "amount": 200
        },
        "rejected": {
          "count": 1,
          "amount": 100
        }
      }
    ]
  }
}

401 SERVER_AUTH_REQUIRED, SIGNATURE_INVALID or SIGNATURE_EXPIRED. Sign the request with your event signing secret, or send the platform secret.

422 RANGE_TOO_LONG or invalid dates.

Show an activity

GET/server/activities/{activityId}

What AdQuest stored for one fact you reported, for support and debugging.

Authentication: Secret Key, sent as the X-AdQuest-Platform-Secret header. Backend only.

ParameterInTypeDescription
activityId requiredpathstringYour id of the fact.
Request, cURL
curl "https://api.adquest.io/api/v1/server/activities/trd_9f31" \
  -H "X-AdQuest-Platform-Secret: YOUR_SECRET_KEY" \
  -H "X-AdQuest-Platform-Key: YOUR_PUBLIC_API_KEY"

200 data has id, type, user, occurred_at, received_at, amount_minor, currency, entity_id, referral_code, state, reverses and reversed_at.

Response 200
{
  "status": true,
  "code": "OK",
  "message": "Activity",
  "data": {
    "id": "trd_9f31",
    "type": "trade.completed",
    "user": "user_123",
    "occurred_at": "2026-11-18T09:59:50+00:00",
    "received_at": "2026-11-18T09:59:51+00:00",
    "amount_minor": null,
    "currency": null,
    "entity_id": "BTC-IRR",
    "referral_code": null,
    "state": null,
    "reverses": null,
    "reversed_at": null
  }
}

401 SERVER_AUTH_REQUIRED, SIGNATURE_INVALID or SIGNATURE_EXPIRED. Sign the request with your event signing secret, or send the platform secret.

404 ACTIVITY_NOT_FOUND.

Register your referral codes

POST/server/referral-codes

Your own referral codes, for referral Quests whose code source is the platform. Each participant holds one code; a code is unique on your platform and moves to the participant it is sent for last. Users AdQuest has not seen are created. Send codes of users who never opened the widget here; participant-sessions also takes referral_code. Register a code before a signup reports it.

Authentication: Secret Key, sent as the X-AdQuest-Platform-Secret header. Backend only.

ParameterInTypeDescription
codes requiredbodyarrayUp to 500 pairs of your user id and that user's code.
Request, cURL
curl -X POST https://api.adquest.io/api/v1/server/referral-codes \
  -H "Content-Type: application/json" \
  -H "X-AdQuest-Platform-Secret: YOUR_SECRET_KEY" \
  -H "X-AdQuest-Platform-Key: YOUR_PUBLIC_API_KEY" \
  -d '{ "codes": [{"user":"55120","code":"ALI2024"}] }'

200 data.results answers each item in order: assigned (with referral_code), or rejected with code INVALID_USER, INVALID_REFERRAL_CODE or DUPLICATE_IN_BATCH (a user or code twice in one request; neither is applied).

Response 200
{
  "status": true,
  "code": "OK",
  "message": "Referral codes received",
  "data": {
    "results": [
      {
        "user": "55120",
        "status": "assigned",
        "referral_code": "ALI2024"
      },
      {
        "user": "55121",
        "status": "rejected",
        "code": "INVALID_REFERRAL_CODE"
      }
    ]
  }
}

401 SERVER_AUTH_REQUIRED, SIGNATURE_INVALID or SIGNATURE_EXPIRED.

422 VALIDATION_ERROR: codes is not a list of 1-500 items.

Next steps

Something unclear, missing or wrong here? Tell us