Quest chain API

Get active quest chains for the user

GET

https://api.onwardinc.net

/v1/quest-chains/active/{platformUserId}

X-API-Key (header)

+X-API-Secret (header)

Publisher

Returns every active quest chain available to one platform user, including ordered tasks and the user's current progress. An unknown user is represented by user.exists: false, setup_status: not_started and an empty quest_chains array. Existing users receive the durable initial setup state through setup_status. See the Platform integration guide for the surrounding workflow.

Get active quest chains for the user › Headers

x-onward-channel

string · enum · required

Required. Where the end user is: web, ios or android -- the channel of this visit, which later actions of the user inherit. Send background on the platform's own calls that are not a user visit (cache warm-up, prefetch, SSR) so they are not counted. A missing or unknown value is recorded as unknown and logged; the request is never rejected over it.

Enum values:

web

ios

android

background

x-onward-user-agent

string

The end user's own User-Agent, forwarded verbatim. Platform servers call Onward server-to-server, so the request's own User-Agent is the platform's HTTP client, not the user's.

Get active quest chains for the user › Responses

Response for status 200

success

boolean · enum · required

Enum values:

object · required

Payload of user's chains response: every active quest chain of one platform user.

Example: {"setup_status":"ready","liveUpdates":{"token":"1b54c84b-6f45-46ee-b49a-2107cc59ab11","baselineTimestamp":null},"quest_chains":[{"quest_chain":{"id":"6f2f6f4e-4a1e-4f6f-9a2b-2c9d1f0b7a31","name":"Welcome chain","description":"Three steps to your first bonus","logo_url":null,"background_image_url":null,"start_date":"2026-07-01T00:00:00+00:00","end_date":"2026-09-01T00:00:00+00:00","status":"active","platform_id":"0b6f5c2a-8a5e-4f0a-9f1b-1d2e3f4a5b6c","advertiser_id":"7d1c9b3a-2f4e-4c8d-9a0b-5e6f7a8b9c0d","allow_any_order":false},"tasks":[{"id":"9a8b7c6d-5e4f-4a3b-8c2d-1e0f9a8b7c6d","sequence_number":1,"name":"Link your account","description":null,"completion_instructions":"Connect your advertiser account and return to the app.","condition_event_type":"link_account","condition_min_amount":null,"condition_currency":null,"condition_after_timestamp":null,"condition_before_timestamp":null,"reward_type":"credit","reward_name":"Starter credit","reward_value":100,"reward_image_urls":null,"reward_outcomes":[{"type":"credit","name":"Starter credit","value":100,"image_urls":null,"weight":1}],"user_status":"completed"}],"user_progress":{"status":"in_progress","progress":33,"joined_at":"2026-07-04T10:15:00+00:00","completed_at":null,"completed_tasks":1,"total_tasks":3},"chain_reward":{"id":"f2e1d0c9-b8a7-46f5-9432-10f9e8d7c6b5","type":"mystery_box","name":"Big prize mystery box","value":null,"image_urls":null,"reward_outcomes":[{"type":"credit","name":"Small win","value":50,"image_urls":null,"weight":8},{"type":"credit","name":"Big win","value":1000,"image_urls":null,"weight":1}],"claimable":false}}],"claimable_tasks":[],"user":{"exists":true}}

details

string

GET/v1/quest-chains/active/{platformUserId}

curl https://api.onwardinc.net/v1/quest-chains/active/:platformUserId \
  --header 'x-onward-channel: <string>' \
  --header 'X-API-Key: <api-key>' \
  --header 'X-API-Secret: <api-key>'

Example Responses

{
  "success": true,
  "data": {
    "setup_status": "ready",
    "liveUpdates": {
      "token": "1b54c84b-6f45-46ee-b49a-2107cc59ab11",
      "baselineTimestamp": null
    },
    "quest_chains": [
      {
        "quest_chain": {
          "id": "6f2f6f4e-4a1e-4f6f-9a2b-2c9d1f0b7a31",
          "name": "Welcome chain",
          "description": "Three steps to your first bonus",
          "logo_url": null,
          "background_image_url": null,
          "start_date": "2026-07-01T00:00:00+00:00",
          "end_date": "2026-09-01T00:00:00+00:00",
          "status": "active",
          "platform_id": "0b6f5c2a-8a5e-4f0a-9f1b-1d2e3f4a5b6c",
          "advertiser_id": "7d1c9b3a-2f4e-4c8d-9a0b-5e6f7a8b9c0d",
          "allow_any_order": false
        },
        "tasks": [
          {
            "id": "9a8b7c6d-5e4f-4a3b-8c2d-1e0f9a8b7c6d",
            "sequence_number": 1,
            "name": "Link your account",
            "description": null,
            "completion_instructions": "Connect your advertiser account and return to the app.",
            "condition_event_type": "link_account",
            "condition_min_amount": null,
            "condition_currency": null,
            "condition_after_timestamp": null,
            "condition_before_timestamp": null,
            "reward_type": "credit",
            "reward_name": "Starter credit",
            "reward_value": 100,
            "reward_image_urls": null,
            "reward_outcomes": [
              {
                "type": "credit",
                "name": "Starter credit",
                "value": 100,
                "image_urls": null,
                "weight": 1
              }
            ],
            "user_status": "completed"
          }
        ],
        "user_progress": {
          "status": "in_progress",
          "progress": 33,
          "joined_at": "2026-07-04T10:15:00+00:00",
          "completed_at": null,
          "completed_tasks": 1,
          "total_tasks": 3
        },
        "chain_reward": {
          "id": "f2e1d0c9-b8a7-46f5-9432-10f9e8d7c6b5",
          "type": "mystery_box",
          "name": "Big prize mystery box",
          "value": null,
          "image_urls": null,
          "reward_outcomes": [
            {
              "type": "credit",
              "name": "Small win",
              "value": 50,
              "image_urls": null,
              "weight": 8
            },
            {
              "type": "credit",
              "name": "Big win",
              "value": 1000,
              "image_urls": null,
              "weight": 1
            }
          ],
          "claimable": false
        }
      }
    ],
    "claimable_tasks": [],
    "user": {
      "exists": true
    }
  },
  "details": "details"
}

json

application/json

Rewards API

Get active quest chains for the user

GET

https://api.onwardinc.net

/v1/quest-chains/active/{platformUserId}

X-API-Key (header)

+X-API-Secret (header)

Publisher

Get active quest chains for the user › Headers

x-onward-channel

string · enum · required

Enum values:

web

ios

android

background

x-onward-user-agent

string

The end user's own User-Agent, forwarded verbatim. Platform servers call Onward server-to-server, so the request's own User-Agent is the platform's HTTP client, not the user's.

Get active quest chains for the user › Responses

Response for status 200

success

boolean · enum · required

Enum values:

object · required

Payload of user's chains response: every active quest chain of one platform user.

details

string