# Report activities

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

Source: https://dashboard.adquest.io/docs/quest-evidence/activities · Audience: Developers · Section: Quest evidence

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

- [Register activities](https://dashboard.adquest.io/docs/dashboard/activities): For publishers: add, edit and check activities in the dashboard.

## 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)**

```typescript
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**

```typescript
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" },
]);
```

| Field | Required | Meaning |
| --- | --- | --- |
| id | Yes | Your unique id for this fact: up to 128 letters, digits, _ . : or -. Sending it again is safe. |
| type | Yes | A registered activity name, such as deposit.completed. |
| user | Yes | Your user id: the external_user_id you use for participant sessions, up to 255 characters. |
| occurred_at | Yes | Unix seconds when it happened on your side. For a state: when the user reached it. |
| amount_minor, currency | When the activity carries an amount | An integer in minor units (cents) as a string, and the registered currency. |
| entity_id | When the activity carries an item id | What the fact is about: an order, a market, a product. |
| state | For a state activity | The value reached, such as verified: up to 64 letters, digits, _ . or -. |
| referral_code | For a signup that came from an invite | The inviter’s code: up to 32 letters and digits. |
| reverses | For a reversal activity | The 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**

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

| Code | What to fix |
| --- | --- |
| UNKNOWN_ACTIVITY_TYPE | The type is not registered for your platform. |
| INVALID_ACTIVITY | id 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_REUSED | The same id was sent before with a different body. Use a new id for a new fact. |
| INVALID_OCCURRED_AT, OCCURRED_AT_OUT_OF_RANGE | occurred_at is not Unix seconds, is more than 60 seconds in the future, or an event is older than 7 days. |
| INVALID_AMOUNT, CURRENCY_MISMATCH | The amount is missing or not an integer, or the currency is not the registered one. |
| ENTITY_ID_REQUIRED | The activity carries an item id and the fact has none. |
| STATE_REQUIRED | A state activity was sent without a state. |
| INVALID_REVERSAL | reverses is missing on a reversal activity, or sent on another activity. |
| INVALID_REFERRAL_CODE | referral_code is not a valid code. |
| STORE_UNAVAILABLE | Retryable. 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**

```typescript
// 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)

| Call | Returns |
| --- | --- |
| GET /server/quests | Your platform’s quests: status, schedule, budget and the activity rules they count. type is the format key, except market_research for surveys. |
| GET /server/fulfillments | Payouts, 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-codes | Registers 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

- [Server routes API](https://dashboard.adquest.io/docs/api/server-routes): Every server request and response.
- [Webhook events](https://dashboard.adquest.io/docs/api/webhook-events#fulfillment-requested): The fulfillment.requested payload.
- [Quest evidence overview](https://dashboard.adquest.io/docs/quest-evidence): What each quest format needs.
