# Rewards API

> Read a participant’s token balance, enter lotteries and submit prize claims.

Source: https://dashboard.adquest.batriders.ir/docs/api/rewards · Audience: Developers · Section: API reference

## Response format

Lottery and claim routes return status, message and data. They do not include a top-level code. When a request fails, read data.code. Balance routes include code.

- [Tokens, lotteries & claims](https://dashboard.adquest.batriders.ir/docs/rewards): How to enter a lottery safely, with idempotency keys.

## Get the token balance

### `GET /platform/balance`

Returns the participant’s current token balance.

**Authentication:** Public API key (X-AdQuest-Platform-Key) and participant token (X-AdQuest-Participant-Token). Both are required.

```bash
curl "https://api.adquest.batriders.ir/api/v1/platform/balance" \
  -H "X-AdQuest-Platform-Key: YOUR_PUBLIC_API_KEY" \
  -H "X-AdQuest-Participant-Token: PARTICIPANT_TOKEN"
```

**Response 200.** The balance.

```json
{
  "status": true,
  "code": "OK",
  "message": "Participant token balance",
  "data": {
    "tokens": 120,
    "platform_user_id": 55,
    "external_user_id": "player-42"
  }
}
```

**Response 401.** PARTICIPANT_AUTH_REQUIRED in data.code. The participant token is missing or invalid.

## Get the balance history

### `GET /platform/balance/history`

Returns the participant’s token transactions, newest first, as a paginated list.

**Authentication:** Public API key (X-AdQuest-Platform-Key) and participant token (X-AdQuest-Participant-Token). Both are required.

| Parameter | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| per_page | query | integer | no | Items per page. Defaults to 15. |
| page | query | integer | no | Page number. |

```bash
curl "https://api.adquest.batriders.ir/api/v1/platform/balance/history" \
  -H "X-AdQuest-Platform-Key: YOUR_PUBLIC_API_KEY" \
  -H "X-AdQuest-Participant-Token: PARTICIPANT_TOKEN"
```

**Response 200.** A paginated list. data holds the page of transactions with the pagination fields (current_page, last_page, per_page, total).

**Response 401.** PARTICIPANT_AUTH_REQUIRED in data.code. The participant token is missing or invalid.

## List lotteries

### `GET /platform/lotteries`

Returns the lotteries visible to this platform and participant country, with active ones first.

**Authentication:** Public API key (X-AdQuest-Platform-Key) and participant token (X-AdQuest-Participant-Token). Both are required.

| Parameter | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| filter | query | string | no | active (default), upcoming, completed or all. |
| per_page | query | integer | no | Items per page. Defaults to 20. |

```bash
curl "https://api.adquest.batriders.ir/api/v1/platform/lotteries" \
  -H "X-AdQuest-Platform-Key: YOUR_PUBLIC_API_KEY" \
  -H "X-AdQuest-Participant-Token: PARTICIPANT_TOKEN"
```

**Response 200.** A page of lotteries.

```json
{
  "status": true,
  "message": "Lotteries list",
  "data": {
    "lotteries": [
      {
        "id": 4,
        "name": "Weekly draw",
        "description": "Win a gift card.",
        "locale": "en",
        "requested_locale": "en",
        "source_locale": "en",
        "is_fallback": false,
        "availability": {
          "policy_type": "global",
          "policy_version": 1,
          "eligibility": "eligible",
          "warning": false,
          "countries": []
        },
        "visibility": "public",
        "entry_cost_tokens": 20,
        "max_entries_per_participant": 5,
        "starts_at": "2026-01-01T00:00:00+00:00",
        "ends_at": "2026-01-08T00:00:00+00:00",
        "lifecycle_status": "active",
        "media_url": null,
        "prize_count": 3,
        "participants_count": 128,
        "hottest_position": 1,
        "my_entry_count": 2,
        "winners_count": null
      }
    ],
    "pagination": {
      "current_page": 1,
      "last_page": 1,
      "per_page": 20,
      "total": 1
    }
  }
}
```

**Response 401.** PARTICIPANT_AUTH_REQUIRED in data.code. The participant token is missing or invalid.

> **Availability.** Each lottery carries an availability object for the participant’s country. A lottery that is not available is hidden from the list and returns 404 when requested directly.

> **Translations.** Lottery and prize text is served from published translations only. The language is the requested one, then the lottery’s source_locale, then the first published translation, then the original English text. locale, requested_locale, source_locale and is_fallback tell you which one you got. Prize text follows the lottery’s language.

## Get a lottery

### `GET /platform/lotteries/{lotteryId}`

Returns one lottery with its prizes and the participant’s own entries.

**Authentication:** Public API key (X-AdQuest-Platform-Key) and participant token (X-AdQuest-Participant-Token). Both are required.

| Parameter | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| lotteryId | path | integer | yes | Lottery ID. |

```bash
curl "https://api.adquest.batriders.ir/api/v1/platform/lotteries/4" \
  -H "X-AdQuest-Platform-Key: YOUR_PUBLIC_API_KEY" \
  -H "X-AdQuest-Participant-Token: PARTICIPANT_TOKEN"
```

**Response 200.** The lottery with its prizes and the participant’s own entry count.

```json
{
  "status": true,
  "message": "Lottery details",
  "data": {
    "lottery": {
      "id": 4,
      "name": "Weekly draw",
      "description": "Win a gift card.",
      "locale": "en",
      "requested_locale": "en",
      "source_locale": "en",
      "is_fallback": false,
      "availability": {
        "policy_type": "global",
        "policy_version": 1,
        "eligibility": "eligible",
        "warning": false,
        "countries": []
      },
      "visibility": "public",
      "entry_cost_tokens": 20,
      "max_entries_per_participant": 5,
      "starts_at": "2026-01-01T00:00:00+00:00",
      "ends_at": "2026-01-08T00:00:00+00:00",
      "lifecycle_status": "active",
      "media_url": null,
      "prize_count": 3,
      "participants_count": 128,
      "hottest_position": 1,
      "awards": [
        {
          "id": 1,
          "name": "Gift card",
          "description": null,
          "locale": "en",
          "requested_locale": "en",
          "source_locale": "en",
          "is_fallback": false,
          "type": "digital",
          "count": 3,
          "priority": 1
        }
      ],
      "my_entry_count": 0,
      "remaining_entries": 5
    }
  }
}
```

**Response 404.** LOTTERY_NOT_FOUND in data.code. The lottery does not exist or is not visible to this platform.

```json
{
  "status": false,
  "message": "Lottery not found",
  "data": {
    "code": "LOTTERY_NOT_FOUND"
  }
}
```

## Enter a lottery

### `POST /platform/lotteries/{lotteryId}/enter`

Spends tokens to buy entries. Send a unique idempotency_key for each purchase and reuse it when you retry after an uncertain response, so the participant is never charged twice.

**Authentication:** Public API key (X-AdQuest-Platform-Key) and participant token (X-AdQuest-Participant-Token). Both are required.

| Parameter | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| lotteryId | path | integer | yes | Lottery ID. |
| entry_count | body | integer | yes | How many entries to buy, 1 to 100. |
| idempotency_key | body | string | yes | Unique key for this purchase attempt. Max 191 characters. |

```bash
curl -X POST https://api.adquest.batriders.ir/api/v1/platform/lotteries/4/enter \
  -H "Content-Type: application/json" \
  -H "X-AdQuest-Platform-Key: YOUR_PUBLIC_API_KEY" \
  -H "X-AdQuest-Participant-Token: PARTICIPANT_TOKEN" \
  -d '{ "entry_count": 2, "idempotency_key": "enter-4-player-42-001" }'
```

**Response 200.** The entries were purchased.

```json
{
  "status": true,
  "message": "Lottery entries purchased",
  "data": {
    "purchase": {
      "id": 301,
      "lottery_id": 4,
      "entry_count": 2,
      "unit_cost_tokens": 20,
      "total_cost_tokens": 40,
      "status": "completed",
      "ticket_numbers": [
        "1G2736",
        "K7Q3X9"
      ]
    },
    "eligibility_snapshot": {
      "country_code": "IR",
      "country_source": "platform",
      "eligibility_status": "eligible",
      "availability_policy_version": 1
    }
  }
}
```

**Response 401.** PARTICIPANT_AUTH_REQUIRED in data.code. The participant token is missing or invalid.

**Response 403.** PREVIEW_READONLY. A theme preview cannot enter lotteries.

**Response 404.** LOTTERY_NOT_FOUND in data.code. The lottery does not exist or is not visible to this platform.

```json
{
  "status": false,
  "message": "Lottery not found",
  "data": {
    "code": "LOTTERY_NOT_FOUND"
  }
}
```

**Response 409.** DUPLICATE_PURCHASE. The idempotency_key was already used for a different lottery or a different participant. Use a new key for each purchase attempt.

```json
{
  "status": false,
  "message": "Duplicate purchase request",
  "data": {
    "code": "DUPLICATE_PURCHASE"
  }
}
```

**Response 422.** Validation failed, or the purchase was refused. data.code says why, for example INSUFFICIENT_TOKENS, LOTTERY_CLOSED or ENTRY_LIMIT_REACHED.

## List my entries

### `GET /platform/lotteries/{lotteryId}/entries`

Returns the participant’s entries and purchases for one lottery.

**Authentication:** Public API key (X-AdQuest-Platform-Key) and participant token (X-AdQuest-Participant-Token). Both are required.

| Parameter | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| lotteryId | path | integer | yes | Lottery ID. |

```bash
curl "https://api.adquest.batriders.ir/api/v1/platform/lotteries/4/entries" \
  -H "X-AdQuest-Platform-Key: YOUR_PUBLIC_API_KEY" \
  -H "X-AdQuest-Participant-Token: PARTICIPANT_TOKEN"
```

**Response 200.** data has entries, purchases and entry_count.

**Response 401.** PARTICIPANT_AUTH_REQUIRED in data.code. The participant token is missing or invalid.

**Response 404.** LOTTERY_NOT_FOUND in data.code. The lottery does not exist or is not visible to this platform.

```json
{
  "status": false,
  "message": "Lottery not found",
  "data": {
    "code": "LOTTERY_NOT_FOUND"
  }
}
```

## Get lottery results

### `GET /platform/lotteries/{lotteryId}/results`

Returns the winners once the lottery is completed. Before that, winners is an empty list.

**Authentication:** Public API key (X-AdQuest-Platform-Key) and participant token (X-AdQuest-Participant-Token). Both are required.

| Parameter | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| lotteryId | path | integer | yes | Lottery ID. |

```bash
curl "https://api.adquest.batriders.ir/api/v1/platform/lotteries/4/results" \
  -H "X-AdQuest-Platform-Key: YOUR_PUBLIC_API_KEY" \
  -H "X-AdQuest-Participant-Token: PARTICIPANT_TOKEN"
```

**Response 200.** data has lifecycle_status and winners. Winners are returned only when lifecycle_status is completed.

```json
{
  "status": true,
  "message": "Lottery results unavailable",
  "data": {
    "lifecycle_status": "active",
    "winners": []
  }
}
```

**Response 404.** LOTTERY_NOT_FOUND in data.code. The lottery does not exist or is not visible to this platform.

```json
{
  "status": false,
  "message": "Lottery not found",
  "data": {
    "code": "LOTTERY_NOT_FOUND"
  }
}
```

## List my tickets

### `GET /platform/lottery-tickets`

Returns every ticket code the participant holds, one group per draw, the draw they entered most recently first.

**Authentication:** Public API key (X-AdQuest-Platform-Key) and participant token (X-AdQuest-Participant-Token). Both are required.

```bash
curl "https://api.adquest.batriders.ir/api/v1/platform/lottery-tickets" \
  -H "X-AdQuest-Platform-Key: YOUR_PUBLIC_API_KEY" \
  -H "X-AdQuest-Participant-Token: PARTICIPANT_TOKEN"
```

**Response 200.** The participant’s ticket codes grouped by draw.

```json
{
  "status": true,
  "message": "My lottery tickets",
  "data": {
    "lotteries": [
      {
        "lottery_id": 4,
        "name": "Weekly draw",
        "ends_at": "2026-02-01T00:00:00+00:00",
        "lifecycle_status": "active",
        "tickets": [
          {
            "ticket_number": "1G2736",
            "has_won": false
          },
          {
            "ticket_number": "K7Q3X9",
            "has_won": false
          }
        ]
      }
    ]
  }
}
```

**Response 401.** PARTICIPANT_AUTH_REQUIRED in data.code. The participant token is missing or invalid.

## List my claims

### `GET /platform/lottery-claims`

Returns the prizes the participant has won, newest first.

**Authentication:** Public API key (X-AdQuest-Platform-Key) and participant token (X-AdQuest-Participant-Token). Both are required.

```bash
curl "https://api.adquest.batriders.ir/api/v1/platform/lottery-claims" \
  -H "X-AdQuest-Platform-Key: YOUR_PUBLIC_API_KEY" \
  -H "X-AdQuest-Participant-Token: PARTICIPANT_TOKEN"
```

**Response 200.** The participant’s claims. Each claim also has an eligibility_snapshot.

```json
{
  "status": true,
  "message": "My lottery claims",
  "data": {
    "claims": [
      {
        "id": 91,
        "lottery_id": 4,
        "lottery_name": "Weekly draw",
        "status": "pending",
        "award_name": "Gift card",
        "award_type": "gift",
        "submitted_at": null,
        "fulfilled_at": null,
        "claim_expires_at": "2026-02-01T00:00:00+00:00"
      }
    ]
  }
}
```

**Response 401.** PARTICIPANT_AUTH_REQUIRED in data.code. The participant token is missing or invalid.

## Submit a claim

### `POST /platform/lottery-claims/{claimId}`

Submits the winner’s claim details. The fields the payload needs depend on the prize and the claim form.

**Authentication:** Public API key (X-AdQuest-Platform-Key) and participant token (X-AdQuest-Participant-Token). Both are required.

| Parameter | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| claimId | path | integer | yes | Claim ID from the claims list. |
| payload | body | object | yes | The claim details the prize requires. |

```bash
curl -X POST https://api.adquest.batriders.ir/api/v1/platform/lottery-claims/91 \
  -H "Content-Type: application/json" \
  -H "X-AdQuest-Platform-Key: YOUR_PUBLIC_API_KEY" \
  -H "X-AdQuest-Participant-Token: PARTICIPANT_TOKEN" \
  -d '{ "payload": {"email":"ada@example.com","name":"Ada"} }'
```

**Response 200.** The claim was submitted. data.claim is the updated claim.

**Response 401.** PARTICIPANT_AUTH_REQUIRED in data.code. The participant token is missing or invalid.

**Response 403.** PREVIEW_READONLY. A theme preview cannot submit claims.

**Response 404.** CLAIM_NOT_AVAILABLE. The claim does not belong to this participant.

**Response 422.** Validation failed, or the claim is closed or expired. data.code says why.