Schemas

Temporary authorization and baseline for quest chain polling.

Active quest chains of the user, each with its tasks and progress. Empty when the user exists but takes part in no active chain, and also empty when the user is unknown — read user.exists to tell those apart.

Tasks from past (expired or completed) quest chains whose reward has not yet been claimed. The user may call the reward-claim endpoint for any of these.

Facts about the requested user that hold regardless of chain membership.

Initial quest-chain setup state: not_started for an unknown user, pending while durable registration work remains retryable, ready after setup completes, and failed after retries are exhausted.

The quest chain this entry describes.

Levels of the chain, ordered by order_by. Contains a single virtual level when levels are disabled.

Progress of the requested user inside this chain.

Final reward of this quest chain, or null when the chain has no final reward.

Quest chain unique identifier.

Quest chain name, safe to show to the user as is.

Long-form quest chain description, or null when the chain has none.

Absolute URL of the chain logo, or null when the chain has none.

Absolute URL of the chain background image, or null when the chain has none.

Moment the chain becomes joinable, ISO 8601 with offset. Null means the chain has no explicit start and is governed by its status alone.

Moment the chain stops accepting progress, ISO 8601 with offset. Null means the chain has no explicit end.

Lifecycle state of the quest chain itself. Only active, cooldown, pending_reward chains are returned by the active-chains endpoint;

Identifier of the platform that owns the chain. Always the caller's own platform.

Identifier of the advertiser funding the chain rewards, or null for a platform-funded chain.

When true the tasks may be completed in any order; when false the chain is step-by-step and unreached tasks are reported with user_status: "locked".

When true the tasks are grouped into levels; when false all tasks belong to a single virtual level.

Level identifier, or null for the virtual common level when the chain has no levels.

Level display name, or null for the virtual common level when the chain has no levels.

Whether the tasks of this level are visible to the user.

Whether all tasks in this level are completed or claimed by the user.

Tasks belonging to this level, ordered by sequence_number.

Task unique identifier. Pass it to the reward-claim endpoint.

Position of the task inside the chain, starting at 1. Tasks arrive already ordered by this field.

Task name, safe to show to the user as is.

Long-form task description, or null when the task has none.

User-facing instructions explaining what the user must do for the task to be considered complete, or null when no additional instructions are configured.

Type of the event that completes this task, for example transaction, link_account or kyc. Send it back through the events endpoint when the user performs the action.

Minimum event amount required to complete the task, or null when the task has no amount condition.

Currency the condition_min_amount is denominated in, for example USD. Null when the task has no amount condition.

Only events at or after this moment can complete the task, ISO 8601 with offset. Null when the task has no lower time bound.

Only events at or before this moment can complete the task, ISO 8601 with offset. Null when the task has no upper time bound.

Reward kind, for example credit, item, multiplier or case. Null when the task carries no reward. For a task completed by a retroactive event this is the retro reward, which may differ from the regular one.

Human-readable reward name, or null when the task carries no reward.

Numeric reward value; meaningful for credit and multiplier rewards. Null when the reward has no numeric value.

Absolute URLs of the reward images, or null when the reward has none.

Every possible outcome this reward can draw, with its weight, or null when the task carries no reward. Has more than one entry only for a reward that draws randomly among several outcomes (a "case"/mystery box) — the reward_type/reward_name/reward_value/reward_image_urls fields above only describe one committed outcome and fall back to a generic case preview in that situation, so a client that wants to show the actual possible prizes and their odds should read this field instead.

State of the task for the requested user, or null when no per-user record exists yet. See QuestChainUserTaskStatus for the individual values.

Identifier of the level this task belongs to, or null when the task is not assigned to any level.

Reward kind of this possible outcome, for example credit, item or multiplier.

Human-readable name of this possible outcome.

Numeric value of this possible outcome; meaningful for credit and multiplier rewards.

Absolute URLs of this outcome's images, or null when it has none.

Draw weight of this outcome relative to the other outcomes of the same reward, for showing odds.

State of this user's participation in the chain.

Completion of the chain in percent, 0 to 100.

Moment the user joined the chain, ISO 8601 with offset.

Moment the user completed the chain, ISO 8601 with offset. Null while the chain is still in progress.

Number of tasks the user has completed or already claimed.

Total number of tasks in the chain.

Identifier of the prize backing this chain's final reward -- never a specific outcome. See reward_outcomes for the possible outcomes when this prize can draw more than one.

Reward code sent to the reward provider, or null when it is not set.

Human-readable reward name, or null when the reward has none.

Numeric reward value, or null when the reward has no numeric value.

Absolute URLs of the reward images, or null when the reward has none.

Every possible outcome this reward can draw, with its weight, or null when the chain has no final reward. See QuestChainTask.reward_outcomes for the same "case"/mystery box semantics.

Whether the requested user can claim this final chain reward now.

Short-lived account connection token received through the Onward OAuth flow.

Identifier of the user in the advertiser's own system.

Advertiser-defined attributes to store with the account connection.

Up to 100 historical events to evaluate after the advertiser account is linked.

Advertiser-defined event type, for example deposit.completed.

Moment the event occurred, formatted as an ISO 8601 UTC timestamp.

Non-negative event amount when the event represents a measurable value.

Currency or unit associated with amount, when applicable.

Advertiser-side idempotency or audit reference for this event.

Additional advertiser-defined event attributes.

Always true when the account connection completed successfully.

Onward user identifier.

Identifier of the user in the platform's system.

Identifier of the user in the advertiser's system.

Validated URL to which the integration should redirect the user.

Identifier of the account-link event created by Onward.

Unique user identifier from your platform

Links the user to the advertiser of the x-advertiser-api-key/secret headers. Platforms do not send it.

ISO 3166-1 alpha-2 country code of the user.

Additional user attributes supplied by the platform.

Advertiser-side user identifier.

Up to 100 historical events to evaluate after the advertiser account is linked.

Internal Onward identifier of the user.

Unique user identifier supplied by the platform.

Moment the user was created, formatted as an ISO 8601 timestamp.

Indicates whether the user already existed at the moment of the request.

Durable user setup state: completed, pending, or failed.

Identifier of the user in the caller's own system: a Platform user ID for Platform credentials or an Advertiser user ID for Advertiser credentials.

Caller-defined event type. Common examples include registration, kyc, link_account, and transaction.

Required ISO 8601 UTC timestamp indicating when the event occurred.

Optional non-negative value associated with the event, such as a deposit or purchase amount.

Optional currency or unit associated with amount, for example an ISO 4217 code.

Optional caller-defined business or audit reference associated with the event.

Additional caller-defined context used for task evaluation, audit, or analytics.

Internal identifier of the recorded event.

The caller-scoped user identifier supplied in the request.

The caller-defined event type supplied in the request.

Moment Onward first recorded the event, formatted as an ISO 8601 timestamp.

received for a newly recorded event or duplicate when the same user, event type, and event timestamp were already recorded.

User's ID on the platform.

Quest chain ID which initiates the account connection.

Where to send the user after the connection completes (success or error)

Identifier of the user in the calling Platform's own system.

Identifier of the completed quest-chain task whose reward the user is claiming.

Identifier of the user's task-progress record that was claimed.

Identifier of the claimed task.

Internal Onward identifier of the user.

ISO 8601 timestamp when the reward claim was recorded.

The reward drawn from the task's mystery box at claim time, or null when the task has no reward configured.

Identifier of the reward configuration that was drawn. Correlates this claim response with the reward.claimed webhook event carrying the same reward_id.

Reward kind, for example credit, item, multiplier, or case. Null when no type is configured.

Configured reward value. It may be a JSON number or a decimal string; null when the reward has no numeric value.

Human-readable reward name, or null when none is configured.

Type of the provider responsible for fulfillment: platform or advertiser.

Internal identifier of the provider responsible for fulfillment.

Additional reward configuration passed to the fulfillment integration.

Absolute URLs of reward images, or null when the reward has none.

User-facing instructions explaining how to receive, redeem, or use the claimed reward.

Identifier of the user in the calling Platform's own system.

Identifier of the completed quest chain whose chain-level reward the user is claiming.

Identifier of the quest chain whose chain-level reward was claimed.

Internal Onward identifier of the user.

ISO 8601 timestamp when the chain reward claim was accepted.

The reward drawn from the chain's mystery box at claim time. A chain reward claim never succeeds without one.

Identifier of the user task or user chain record that owns the claim.

Whether the reward was claimed for a task or for completing a quest chain.

Task identifier for task claims, or quest-chain identifier for chain claims.

Quest-chain identifier associated with the claim, when available.

ISO 8601 timestamp when the reward claim was recorded.

Reward configuration resolved at the moment of claim.