# 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.

Source: https://dashboard.adquest.io/docs/api/server-routes · Audience: Developers · Section: API reference

## 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.

- [Report activities](https://dashboard.adquest.io/docs/quest-evidence/activities): A signing helper, examples and what counts.

## 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.

| Parameter | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| claimId | path | integer | yes | Claim ID from the lottery.winner webhook. |
| external_user_id | body | string | yes | Your ID for the winner. Max 255 characters. |
| email | body | string | no | The winner’s email. Max 255 characters. Required unless your platform notifies its winners itself. |
| display_name | body | string | no | The winner’s name. Max 255 characters. |

```bash
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"
}'
```

**Response 200.** The contact was received.

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

**Response 401.** The Secret Key is missing or wrong.

**Response 403.** The platform is not accepted and active.

**Response 404.** CLAIM_NOT_AVAILABLE.

**Response 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.

| Parameter | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| activities | body | array | yes | The facts, at most 500. |

```bash
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"}] }'
```

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

```json
{
  "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"
      }
    ]
  }
}
```

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

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

**Response 413.** BATCH_TOO_LARGE: more than 500 items or 512 KB.

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

**Response 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.

| Parameter | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| id | path | integer | yes | Fulfillment ID from the fulfillment.requested webhook. |
| external_reference | body | string | yes | Your own reference for the delivered reward. |

```bash
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" }'
```

**Response 200.** data has id, status, external_reference and rejection_reason.

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

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

**Response 404.** FULFILLMENT_NOT_FOUND.

**Response 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.

| Parameter | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| id | path | integer | yes | Fulfillment ID from the fulfillment.requested webhook. |
| reason_code | body | string | yes | Your reason, lowercase letters, digits and _. |

```bash
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" }'
```

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

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

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

**Response 404.** FULFILLMENT_NOT_FOUND.

**Response 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.

| Parameter | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| status | query | string | no | pending, delivered, acknowledged, rejected, failed or terminal_failed. |
| created_from | query | string | no | Only fulfillments created at or after this time. |
| created_to | query | string | no | Only fulfillments created before this time. |
| after | query | string | no | The `next` value of the previous page. |
| limit | query | integer | no | Page size, 1 to 200. Default 50. |

```bash
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"
```

**Response 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.

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

**Response 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.

| Parameter | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| updated_since | query | string | no | Only quests changed at or after this time. |
| after | query | string | no | The `next` value of the previous page. |
| limit | query | integer | no | Page size, 1 to 200. Default 50. |

```bash
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"
```

**Response 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).

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

**Response 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.

| Parameter | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| from | query | string | yes | First UTC day, inclusive. |
| to | query | string | yes | Exclusive. |

```bash
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"
```

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

```json
{
  "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
        }
      }
    ]
  }
}
```

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

**Response 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.

| Parameter | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| activityId | path | string | yes | Your id of the fact. |

```bash
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"
```

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

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

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

**Response 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.

| Parameter | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| codes | body | array | yes | Up to 500 pairs of your user id and that user's code. |

```bash
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"}] }'
```

**Response 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).

```json
{
  "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"
      }
    ]
  }
}
```

**Response 401.** SERVER_AUTH_REQUIRED, SIGNATURE_INVALID or SIGNATURE_EXPIRED.

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

## Next steps

- [Webhook events](https://dashboard.adquest.io/docs/api/webhook-events): The notifications that lead to these calls.
- [Webhooks guide](https://dashboard.adquest.io/docs/webhooks): Register and verify an endpoint.
