Add custom points to users

Introduction

Add points to your users' balances in claimr. Use these methods to reward your users in claimr based on actions they complete outside the platform — for example, in your own app or product. This effectively syncs off-platform activity with your claimr reward system.

Benefits of adding points from external actions

  • Expand engagement: Extend user engagement beyond the claimr platform by rewarding activity in your own application or product.

  • Reward specific behaviors: Recognize and incentivize particular actions or achievements that occur outside of claimr.

  • Create a holistic reward system: Build a unified reward experience that combines both in-claimr and external user activities.

You can add points to user balances in claimr through three primary mechanisms, each leveraging specific API endpoints. The method you choose depends on how you want to track and reward the external user activity.

1. Direct point management (Using API)

These API calls allow you to directly add points (POST /user/reward) or deduct points (POST /user/withdraw) from a user's balance in claimr.

You can initiate these requests from your external system to claimr, specifying the user, campaign, and the amount of points to add or remove.

POST /user/reward

  • Purpose: Use this endpoint to reward your users in claimr based on actions they complete outside the platform — for example, in your own app or product. This allows you to sync off-platform activity with your claimr reward system.

  • Process: This action occurs in the background. The user receives points through this API request, and these points automatically appear in claimr.

  • Body (JSON request example):

{
  "account": "string",
  "platform": "string",
  "pid": "string",
  "id": "string",
  "kind": "string",
  "xp": 0,
  "env": "string"
}

account: The user's account identifier in your platform (e.g., email, nickname, ID).

platform: Platform identifier.

pid: Campaign ID.

id: A unique identifier for each reward given to a specific user. If this ID is not unique for a given user, the reward will be ignored.

xp: The number of points you are assigning to the user (e.g., 100 points).

  • JSON Response (Success):

{
    "success": true
}

POST /user/withdraw

  • Purpose: This endpoint allows you to deduct or withdraw points from your users' balances in claimr. This is useful for adjusting user points based on actions outside of claimr or for managing specific campaign mechanics.

  • Process: This action occurs in the background. The specified points are deducted from the user's balance in claimr.

  • Body (JSON request example):

{
  "account": "user123",
  "platform": "steam",
  "pid": "campaign_abc123",
  "id": "withdraw_xyz789",
  "kind": "items_shop",
  "xp": 100,
  "env": "string",
  "strict": true
}

account: The user's account identifier in your platform (e.g., email, nickname, ID).

platform: Platform identifier.

pid: Campaign ID.

id: A unique identifier for each withdrawal transaction given to a specific user. This ID ensures that the withdrawal is processed only once.

xp: The number of points you wish to withdraw from the user's balance (e.g., 50 points).

strict: (Meaning not explicitly provided, but included in the JSON structure).

  • JSON Response (Success):

{
    "success": true
}

Monitoring points in Analytics

To view a user's detailed information:

  1. Navigate to the Analytics section.

  2. Select the relevant table (e.g., Activity, Referrals).

  3. Find the user in the table.

  4. Click on the user's row. This will open a modal window with a comprehensive overview.

  5. Go to the points section within this modal. It shows many points were earned from various sources and allows you to adjust manually the user's total points if needed.

Withdrawn points are any reductions to a user's total points, such as penalties or corrections applied via the claimr API.

All information about the points for each user can be checked in our User information.

2. API tasks: stream and action value

POST /stream/value and POST /action/value methods are used when you want to reward users based on continuous value streams or specific actions that carry a quantifiable value.

You can configure these tasks by navigating to Task → API in the claimr admin panel and choosing one of the following task types.

POST /action/value

  • POST /action/value supports two types of API tasks:

    • API Number value tasks: Used when you need to track an expected numerical result. For example, a user earns a reward once a specific target (like receiving 10 likes) is reached.

    • API Score tasks: Used for directly adding a score or a specific amount of points to a user's total, immediately changing their balance.

  • Body (JSON request example):

    {
  "account": "user123",
  "platform": "steam",
  "pid": "campaign_abc123",
  "cid": "quest_xyz789",
  "aid": "score_update",
  "value": 150,
  "env": "string"
}

    • account: User identifier.

    • platform: Platform identifier.

    • pid: Campaign ID.

    • cid: Quest ID.

    • aid: Action ID.

    • value: The numeric value to set or update.

  • JSON Response (Success):

    {
"success": true
}

POST /stream/value

  • POST /stream/value specifically supports the task type API Stream Value. It accumulates numeric attributes associated with user actions (e.g., total transactions).

  • Body (JSON request example):

{
  "account": "user123",
  "platform": "steam",
  "pid": "campaign_abc123",
  "stream": "player_score",
  "value": 250,
  "env": "string"
}

  • account: User identifier.

  • platform: Platform identifier.

  • stream: Attribute stream ID.

  • pid: Campaign ID.

  • value: The numeric value to accumulate.

  • JSON Response (Success):

{
    "success": true
}

3: Events task

If your product or app generates user actions that you'd like to track and reward (for example, gameplay sessions or completed actions), you can use event-based tasks in claimr. These are flexible and work by sending structured event data to claimr, which then checks whether it matches your task criteria.

In this guide, we’ll show two types of tasks using real data from Wowhaus:

  • Custom Events Count (e.g., number of dice rolls)

  • Custom Events Value (e.g., total amount bet)

How POST /event works

This endpoint allows your application to send event data to claimr. If the event matches an existing task (by platform, category, name, and optionally a query), the user is rewarded accordingly.

Body (JSON request example):

This payload represents a user who started a game session and placed a bet of 250. Depending on the task setup, this same event can be used to track either the number of sessions (Event Count) or the value of bets (Event Value).

POST https://prod.claimr.io/api/v1/event
Headers:
  Authorization: Bearer YOUR_PERSONAL_API_TOKEN
  Content-Type: application/json
  Accept: application/json

Body:
{
  "account": "user123",              
  "platform": "wowhaus",             
  "pid": "H_wie9sz",                 
  "category": "dices",               
  "name": "GameSession",             
  "data": {
    "bet": 250                       
  }
}

Replace YOUR_PERSONAL_API_TOKEN with a valid token generated from your claimr account.

  • account: A unique identifier for the user (e.g., their email, nickname, or internal user ID within your platform).

  • platform: An identifier indicating the platform where the user's action or account originates.

  • pid: The Campaign ID to which this event belongs.

  • category: A broad classification for the event (e.g., "game", "transaction"). This helps in filtering events later.

  • name: The specific name of the action or event (e.g., "level_up", "purchase_complete").

  • data: A nested object that holds the detailed attributes of the event: scores, levels, durations, amounts, or any other numeric or descriptive values relevant to the action being tracked.

  • ts: The timestamp of the event from your client's system.

JSON Response (Success):

{
  "success": true
}

How account and platform are linked

The account and platform fields define how users are identified in claimr:

  • If you're using a user token, these values usually come from your authentication method.

  • If users log in via wallet address, then the platform is web3.

  • If you're using Telegram mini-apps, the account could be the Telegram User ID and the platform set to telegram.

This flexibility allows you to send events from different apps or sources while still attributing them to the correct user in claimr.

Connecting Events to tasks

The examples below show how to configure Events tasks in claimr based on real gameplay data from the Wowhaus platform.

The two main types covered below are:

  • Custom Events Count – tracks how many times an event occurred.

  • Custom Events Value – tracks the total numeric value received from an event.

When you create a task in claimr with the type Events, claimr listens for POST /event calls matching the criteria you define.

Custom Events Count

Use this setup when you want to reward users for repeating an action a specific number of times. Example: users are rolling the dice in a game.

  • Completion points: 100

    The number of points the user receives after completing the task conditions.

  • Points multiplier (%): 5%

    A 5% multiplier means the user receives 105 points (the base amount of 100 points + 5%).

  • Recurrence: Daily

    The task can be completed once a day. After 24 hours, it resets for the user.

  • Event Category: dices

    This is a label used to group similar events. In this case, it's related to dice gameplay.

  • Event Name: GameSession

    The exact name of the event to track. It must match the “name” field in the POST /event body.

  • Platform: wowhaus

    Identifies the integration source. In this case, Wowhaus is the platform where the events come from.

  • Events Count: 5

    The user must perform the action 5 times to earn the reward.

  • Button Text: “Claim your reward”

    The custom label for the CTA button displayed on the quest.

  • Is progressive reward: Enabled

    Rewards scale based on how much the user exceeds the required count. If the user rolls 30 times (instead of 10), they earn 3× the base reward.

  • Is continuous: Enabled

    The task stays active and resets based on the recurrence logic. Users can keep earning rewards every day if they meet the conditions again.

Explanation

This setup tracks how many times a user sends the GameSession event under the dices category. Once the event count reaches 5, the user is awarded 105 points. Because progressive rewards are enabled, additional actions (e.g., 30 rolls) result in proportionally higher rewards. The enabled “continuous” toggle means this task stays active and can be completed again each day.

Custom Events Value

Use this task type when you want to reward a user once the total value sent through event data reaches a specific threshold. Example: users set bets in a dice game.

  • Completion points: 100

    The number of points the user receives after completing the task conditions.

  • Points multiplier (%): 5%

    A 5% multiplier means the user receives 105 points (the base amount of 100 points + 5%).

  • Recurrence: Once

    The task can be completed only once. It doesn't reset.

  • Event Category: dices

    This is a label used to group similar events. In this case, it's related to dice gameplay.

  • Event Name: GameSession

    The exact name of the event to track. It must match the “name” field in the POST /event body.

  • Platform: wowhaus

    Identifies the integration source. In this case, Wowhaus is the platform where the events come from.

  • Query: [].data.bet

    This JMESPath query extracts the bet value from each received event.

  • Events Value: 500

    The task is triggered when the total of all data.bet values reaches 500.

  • Button Text: “Claim your reward”

    The custom label for the CTA button displayed on the quest.

  • Is progressive reward: Disabled

    Even if the user exceeds the 500 bet value, they still receive the same fixed reward (105 points with multiplier).

  • Is continuous: Disabled

    Once completed, the task is marked as done. Users won’t earn additional rewards if the task resets the following day.

Query example for Events Value

To extract the bet value from incoming event data, use this JMESPath query:

[].data.bet

This will return the list of bet amounts across all received events.

Explanation:

This task listens for GameSession events in the dices category. It uses the [].data.bet JMESPath query to extract numeric bet values from each event. Once the combined total reaches 500, claimr grants 100 base points, boosted to 105 points by the 5% multiplier. Because both toggles are off, the user earns the reward only once and receives a fixed amount, regardless of how much they exceed the threshold.

For more information about the settings, read our article Events tasks.

PreviousCustomize user experience with tags and attributesNextUX requirements

Last updated

Was this helpful?