API reference

View as MarkdownPlain text for LLMs Open in ClaudeAsk questions about this page Open in ChatGPTAsk questions about this page

Rewards API

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

On this page

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 & claimsHow 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.

Request, cURL

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"

200 The balance.

Response 200

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

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	Description
`per_page`	query	integer	Items per page. Defaults to 15.
`page`	query	integer	Page number.

Request, cURL

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"

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

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	Description
`filter`	query	string	active (default), upcoming, completed or all.
`per_page`	query	integer	Items per page. Defaults to 20.

Request, cURL

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"

200 A page of lotteries.

Response 200

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

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

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	Description
`lotteryId` required	path	integer	Lottery ID.

Request, cURL

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"

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

Response 200

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

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

Response 404

{
  "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	Description
`lotteryId` required	path	integer	Lottery ID.
`entry_count` required	body	integer	How many entries to buy, 1 to 100.
`idempotency_key` required	body	string	Unique key for this purchase attempt. Max 191 characters.

Request, cURL

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

200 The entries were purchased.

Response 200

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

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

403 PREVIEW_READONLY. A theme preview cannot enter lotteries.

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

Response 404

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

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.

Response 409

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

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	Description
`lotteryId` required	path	integer	Lottery ID.

Request, cURL

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"

200 data has entries, purchases and entry_count.

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

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

Response 404

{
  "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	Description
`lotteryId` required	path	integer	Lottery ID.

Request, cURL

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"

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

Response 200

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

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

Response 404

{
  "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.

Request, cURL

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"

200 The participant’s ticket codes grouped by draw.

Response 200

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

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.

Request, cURL

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"

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

Response 200

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

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	Description
`claimId` required	path	integer	Claim ID from the claims list.
`payload` required	body	object	The claim details the prize requires.

Request, cURL

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

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

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

403 PREVIEW_READONLY. A theme preview cannot submit claims.

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

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