API reference

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

Server routes API

Routes your backend calls: winner contact, fulfillment acknowledgements and streak callbacks.

On this page

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.

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

Parameter	In	Type	Description
`claimId` required	path	integer	Claim ID from the lottery.winner webhook.
`external_user_id` required	body	string	Your ID for the winner. Max 255 characters.
`email` required	body	string	The winner’s email. Max 255 characters.
`display_name` required	body	string	The winner’s name. Max 255 characters.

Request, cURL

curl -X POST https://api.adquest.batriders.ir/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.

Acknowledge a fulfillment

POST/platform/fulfillments/{fulfillmentId}/acknowledge

Confirms that you delivered a reward announced by a fulfillment.requested webhook. Repeating the same external_reference is safe.

Authentication: Public API key (X-AdQuest-Platform-Key).

Parameter	In	Type	Description
`fulfillmentId` required	path	integer	Fulfillment ID from the webhook.
`external_reference` required	body	string	Your own reference for the delivered reward. Max 190 characters.

Request, cURL

curl -X POST https://api.adquest.batriders.ir/api/v1/platform/fulfillments/12/acknowledge \
  -H "Content-Type: application/json" \
  -H "X-AdQuest-Platform-Key: YOUR_PUBLIC_API_KEY" \
  -d '{ "external_reference": "order-8841" }'

200 The fulfillment was acknowledged. data has id, kind, status, amount, asset, external_reference, last_failure_reason, acknowledged_at, quest_completion_id, lottery_claim_id and created_at.

404 The fulfillment was not found.

409 FULFILLMENT_CONFLICT. It was already acknowledged with a different external_reference.

Record a streak day from the creator callback URL

POST/streak-callbacks/{token}

Records one day of a streak quest. Call the callback URL from your backend after the user finishes that day’s action. GET works too, with user_id as a query parameter. A streak STEP of a multi-step quest has its own per-participant callback URL (callback_url in that step of the execution state); user_id is then optional and, if sent, must match the participant. The last day verifies only that step; the parent quest settles separately (data.step_verified, data.settlement_status).

Authentication: None.

Parameter	In	Type	Description
`token` required	path	string	The 64-character hex token from the quest’s callback URL.
`Idempotency-Key`	header	string	Optional key to make a retry safe.
`user_id` required	body	string	Your stable ID for the user. external_user_id, userId and externalUserId are accepted as aliases.

Request, cURL

curl -X POST https://api.adquest.batriders.ir/api/v1/streak-callbacks/CALLBACK_TOKEN \
  -H "Content-Type: application/json" \
  -d '{ "user_id": "player-123" }'

200 The day was recorded. On the last day the quest completes and data also holds tokens_awarded.

Response 200

{
  "status": true,
  "code": "OK",
  "message": "Streak day recorded",
  "data": {
    "completed": false,
    "quest_id": 7800,
    "external_user_id": "player-123",
    "streak": {
      "current_day": 2,
      "day_count": 7,
      "status": "active",
      "unlocked": false,
      "next_unlock_at": "2026-09-14T12:00:00+00:00",
      "last_completed_day": 1,
      "day_number": 1,
      "micro_rewarded": false,
      "final_rewarded": false,
      "idempotent": false
    }
  }
}

404 STREAK_CALLBACK_NOT_FOUND. The token does not match a quest.

422 INVALID_STREAK_USER or another streak error. data.reason says why.

429 RATE_LIMITED.

Record a streak day (GET)

GET/streak-callbacks/{token}

Same as the POST route, with user_id as a query parameter. Use POST when you can.

Authentication: None.

Parameter	In	Type	Description
`token` required	path	string	The 64-character hex token from the quest’s callback URL.
`user_id` required	query	string	Your stable ID for the user. external_user_id is accepted as an alias.

Request, cURL

curl "https://api.adquest.batriders.ir/api/v1/streak-callbacks/CALLBACK_TOKEN?user_id=player-123"

200 The day was recorded. On the last day the quest completes and data also holds tokens_awarded.

Response 200

{
  "status": true,
  "code": "OK",
  "message": "Streak day recorded",
  "data": {
    "completed": false,
    "quest_id": 7800,
    "external_user_id": "player-123",
    "streak": {
      "current_day": 2,
      "day_count": 7,
      "status": "active",
      "unlocked": false,
      "next_unlock_at": "2026-09-14T12:00:00+00:00",
      "last_completed_day": 1,
      "day_number": 1,
      "micro_rewarded": false,
      "final_rewarded": false,
      "idempotent": false
    }
  }
}

404 STREAK_CALLBACK_NOT_FOUND. The token does not match a quest.

422 INVALID_STREAK_USER or another streak error. data.reason says why.

429 RATE_LIMITED.

Next steps

Webhook eventsThe notifications that lead to these calls.Webhooks guideRegister and verify an endpoint.

Post a winner’s contact#

Acknowledge a fulfillment#

Record a streak day from the creator callback URL#

Record a streak day (GET)#

Next steps#

Post a winner’s contact

Acknowledge a fulfillment

Record a streak day from the creator callback URL

Record a streak day (GET)

Next steps