Rewards API

Claim task-level and quest-chain-level rewards and inspect claim history.

Claim a task reward

POST

https://api.onwardinc.net

/v1/rewards/claim

X-API-Key (header)

+X-API-Secret (header)

Publisher

Claims the reward for a completed quest-chain task belonging to the calling Platform. The claim is recorded once, reward delivery is attempted immediately, and any pending delivery is retried asynchronously.

Claim a task reward › Headers

x-onward-channel

string · enum

Optional. Where the end user is: web, ios or android. Without it the action is attributed to the channel of the user's last GET /v1/quest-chains/active call.

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.

Claim a task reward › Request Body

Claims the reward attached to a completed task for a user belonging to the calling Platform. A task reward can be claimed only once.

platform_user_id

string · minLength: 1 · maxLength: 255 · required

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

Example: user_12345

task_id

string · uuid · required

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

Example: 9a8b7c6d-5e4f-4a3b-8c2d-1e0f9a8b7c6d

Claim a task reward › Responses

Response for status 200

success

boolean · enum · required

Indicates that the request was successful.

Enum values:

object · required

Identifiers, timestamp, and the drawn reward of the successfully recorded task reward claim.

Example: {"user_task_id":"550e8400-e29b-41d4-a716-446655440000","task_id":"9a8b7c6d-5e4f-4a3b-8c2d-1e0f9a8b7c6d","user_id":"550e8400-e29b-41d4-a716-446655440001","claimed_at":"2026-08-20T12:30:00Z","reward":{"id":"3f3d1c4e-9a5b-4c7d-8e2f-3a4b5c6d7e8f","type":"credit","value":100,"name":"Welcome bonus","provider_type":"platform","provider_id":"0b6f5c2a-8a5e-4f0a-9f1b-1d2e3f4a5b6c","metadata":{"currency":"USD"},"image_urls":["https://cdn.example.com/rewards/welcome-bonus.png"],"redemption_instructions":"Apply the voucher code at checkout."}}

POST/v1/rewards/claim

curl https://api.onwardinc.net/v1/rewards/claim \
  --request POST \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: <api-key>' \
  --header 'X-API-Secret: <api-key>' \
  --data '{
  "platform_user_id": "user_12345",
  "task_id": "9a8b7c6d-5e4f-4a3b-8c2d-1e0f9a8b7c6d"
}'

Example Request Body

{
  "platform_user_id": "user_12345",
  "task_id": "9a8b7c6d-5e4f-4a3b-8c2d-1e0f9a8b7c6d"
}

json

Example Responses

{
  "success": true,
  "data": {
    "user_task_id": "550e8400-e29b-41d4-a716-446655440000",
    "task_id": "9a8b7c6d-5e4f-4a3b-8c2d-1e0f9a8b7c6d",
    "user_id": "550e8400-e29b-41d4-a716-446655440001",
    "claimed_at": "2026-08-20T12:30:00Z",
    "reward": {
      "id": "3f3d1c4e-9a5b-4c7d-8e2f-3a4b5c6d7e8f",
      "type": "credit",
      "value": 100,
      "name": "Welcome bonus",
      "provider_type": "platform",
      "provider_id": "0b6f5c2a-8a5e-4f0a-9f1b-1d2e3f4a5b6c",
      "metadata": {
        "currency": "USD"
      },
      "image_urls": [
        "https://cdn.example.com/rewards/welcome-bonus.png"
      ],
      "redemption_instructions": "Apply the voucher code at checkout."
    }
  }
}

json

application/json

Claim a quest-chain reward

POST

https://api.onwardinc.net

/v1/chains/rewards/claim

X-API-Key (header)

+X-API-Secret (header)

Publisher

Claims the reward attached to the quest chain itself after the user's chain reaches pending_reward. This is separate from task rewards; chain finalization and any pending reward delivery continue asynchronously.

Claim a quest-chain reward › Headers

x-onward-channel

string · enum

Optional. Where the end user is: web, ios or android. Without it the action is attributed to the channel of the user's last GET /v1/quest-chains/active call.

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.

Claim a quest-chain reward › Request Body

Claims the reward attached to the quest chain itself after the user's chain reaches `pending_reward`. This is separate from rewards attached to individual tasks.

platform_user_id

string · minLength: 1 · maxLength: 255 · required

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

Example: user_12345

quest_chain_id

string · uuid · required

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

Example: 6f2f6f4e-4a1e-4f6f-9a2b-2c9d1f0b7a31

Claim a quest-chain reward › Responses

Response for status 200

success

boolean · enum · required

Indicates that the request was successful.

Enum values:

object · required

Identifiers, timestamp, and the drawn reward of the accepted quest-chain reward claim.

Example: {"quest_chain_id":"6f2f6f4e-4a1e-4f6f-9a2b-2c9d1f0b7a31","user_id":"550e8400-e29b-41d4-a716-446655440001","claimed_at":"2026-08-20T12:35:00Z","reward":{"id":"3f3d1c4e-9a5b-4c7d-8e2f-3a4b5c6d7e8f","type":"credit","value":500,"name":"Chain completion bonus","provider_type":"platform","provider_id":"0b6f5c2a-8a5e-4f0a-9f1b-1d2e3f4a5b6c","metadata":{"currency":"USD"},"image_urls":["https://cdn.example.com/rewards/chain-bonus.png"],"redemption_instructions":"Open the reward in your account and follow the activation steps."}}

POST/v1/chains/rewards/claim

curl https://api.onwardinc.net/v1/chains/rewards/claim \
  --request POST \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: <api-key>' \
  --header 'X-API-Secret: <api-key>' \
  --data '{
  "platform_user_id": "user_12345",
  "quest_chain_id": "6f2f6f4e-4a1e-4f6f-9a2b-2c9d1f0b7a31"
}'

Example Request Body

{
  "platform_user_id": "user_12345",
  "quest_chain_id": "6f2f6f4e-4a1e-4f6f-9a2b-2c9d1f0b7a31"
}

json

Example Responses

{
  "success": true,
  "data": {
    "quest_chain_id": "6f2f6f4e-4a1e-4f6f-9a2b-2c9d1f0b7a31",
    "user_id": "550e8400-e29b-41d4-a716-446655440001",
    "claimed_at": "2026-08-20T12:35:00Z",
    "reward": {
      "id": "3f3d1c4e-9a5b-4c7d-8e2f-3a4b5c6d7e8f",
      "type": "credit",
      "value": 500,
      "name": "Chain completion bonus",
      "provider_type": "platform",
      "provider_id": "0b6f5c2a-8a5e-4f0a-9f1b-1d2e3f4a5b6c",
      "metadata": {
        "currency": "USD"
      },
      "image_urls": [
        "https://cdn.example.com/rewards/chain-bonus.png"
      ],
      "redemption_instructions": "Open the reward in your account and follow the activation steps."
    }
  }
}

json

application/json

List claimed rewards

GET

https://api.onwardinc.net

/v1/rewards/claimed/{platformUserId}

X-API-Key (header)

+X-API-Secret (header)

Publisher

Returns task and quest-chain rewards claimed by a user belonging to the calling Platform, ordered from newest to oldest. Pass the returned next_cursor to continue from the following item.

List claimed rewards › path Parameters

platformUserId

string · minLength: 1 · maxLength: 255 · required

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

Example: user_12345

List claimed rewards › query Parameters

limit

integer · max: 100 · required

Maximum number of claimed rewards returned per page.

Example: 50

Default: 50

cursor

string · minLength: 1 · maxLength: 512

Opaque cursor returned as pagination.next_cursor by the previous page. Omit it for the first page.

List claimed rewards › Responses

Response for status 200

anyOf

At least one variant must match. Multiple variants may match simultaneously.

Decision Table

Variant	Matching Criteria
	type = object · requires: success, data, pagination
	type = object · requires: success, error

Properties for Variant 1:

success

boolean · enum · required

Indicates that the request was successful.

Enum values:

object[] · required

object · required

GET/v1/rewards/claimed/{platformUserId}

curl 'https://api.onwardinc.net/v1/rewards/claimed/:platformUserId?limit=50' \
  --header 'X-API-Key: <api-key>' \
  --header 'X-API-Secret: <api-key>'

Example Responses

{
  "success": true,
  "data": [
    {
      "claim_id": "00000000-0000-0000-0000-000000000000",
      "source_type": "task",
      "source_id": "00000000-0000-0000-0000-000000000000",
      "quest_chain_id": "00000000-0000-0000-0000-000000000000",
      "claimed_at": "2026-08-20T12:30:00Z",
      "reward": {
        "id": "3f3d1c4e-9a5b-4c7d-8e2f-3a4b5c6d7e8f",
        "type": "credit",
        "value": 100,
        "name": "Welcome bonus",
        "provider_type": "platform",
        "provider_id": "0b6f5c2a-8a5e-4f0a-9f1b-1d2e3f4a5b6c",
        "metadata": {
          "currency": "USD"
        },
        "image_urls": [
          "https://cdn.example.com/rewards/welcome-bonus.png"
        ],
        "redemption_instructions": "Show the voucher code at checkout before 31 December."
      }
    }
  ],
  "pagination": {
    "limit": 1,
    "next_cursor": "next_cursor"
  }
}

json

application/json

Events API Quest chain API

Claim a task reward

POST

https://api.onwardinc.net

/v1/rewards/claim

X-API-Key (header)

+X-API-Secret (header)

Publisher

Claim a task reward › Headers

x-onward-channel

string · enum

Optional. Where the end user is: web, ios or android. Without it the action is attributed to the channel of the user's last GET /v1/quest-chains/active call.

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.

Claim a task reward › Request Body

Claims the reward attached to a completed task for a user belonging to the calling Platform. A task reward can be claimed only once.

platform_user_id

string · minLength: 1 · maxLength: 255 · required

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

Example: user_12345

task_id

string · uuid · required

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

Example: 9a8b7c6d-5e4f-4a3b-8c2d-1e0f9a8b7c6d

Claim a task reward › Responses

Response for status 200

success

boolean · enum · required

Indicates that the request was successful.

Enum values:

object · required

Identifiers, timestamp, and the drawn reward of the successfully recorded task reward claim.

Claim a quest-chain reward

POST

https://api.onwardinc.net

/v1/chains/rewards/claim

X-API-Key (header)

+X-API-Secret (header)

Publisher

Claim a quest-chain reward › Headers

x-onward-channel

string · enum

Optional. Where the end user is: web, ios or android. Without it the action is attributed to the channel of the user's last GET /v1/quest-chains/active call.

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.

Claim a quest-chain reward › Request Body

Claims the reward attached to the quest chain itself after the user's chain reaches `pending_reward`. This is separate from rewards attached to individual tasks.

platform_user_id

string · minLength: 1 · maxLength: 255 · required

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

Example: user_12345

quest_chain_id

string · uuid · required

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

Example: 6f2f6f4e-4a1e-4f6f-9a2b-2c9d1f0b7a31

Claim a quest-chain reward › Responses

Response for status 200

success

boolean · enum · required

Indicates that the request was successful.

Enum values:

object · required

Identifiers, timestamp, and the drawn reward of the accepted quest-chain reward claim.

List claimed rewards

GET

https://api.onwardinc.net

/v1/rewards/claimed/{platformUserId}

X-API-Key (header)

+X-API-Secret (header)

Publisher

Returns task and quest-chain rewards claimed by a user belonging to the calling Platform, ordered from newest to oldest. Pass the returned next_cursor to continue from the following item.

List claimed rewards › path Parameters

platformUserId

string · minLength: 1 · maxLength: 255 · required

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

Example: user_12345

List claimed rewards › query Parameters

limit

integer · max: 100 · required

Maximum number of claimed rewards returned per page.

Example: 50

Default: 50

cursor

string · minLength: 1 · maxLength: 512

Opaque cursor returned as pagination.next_cursor by the previous page. Omit it for the first page.

List claimed rewards › Responses

Response for status 200

anyOf

At least one variant must match. Multiple variants may match simultaneously.

Decision Table

Variant	Matching Criteria
	type = object · requires: success, data, pagination
	type = object · requires: success, error

Properties for Variant 1:

success

boolean · enum · required

Indicates that the request was successful.

Enum values:

object[] · required

object · required