API methods: the full reference for integrating with claimr

Webhooks

Manage real-time event updates by subscribing to specific user activities through webhooks.

POST /hook

{
  "scope": "user_activity",
  "uri": "https://example.com/webhook",
  "secret": "my-secret-key",
  "hook_id": "prod",
  "pids": []
}

Field explanations:

scope: The type of event you want to track. Use user_activity to receive updates on user actions such as referrals, task completions, or deposits.
uri: The full URL where claimr should send the webhook notifications. This must be a valid HTTPS endpoint you control.
secret: A string used to verify the authenticity of webhook requests.
hook_id: A custom ID you assign to the webhook. Helps you manage multiple environments.
pids: A list of campaign IDs. If provided, notifications will be limited to the specified campaigns. Leave empty to subscribe to all campaigns.

Example response:

{
  "success": true
}

DELETE /hook

Unregister an existing webhook to stop receiving notifications for a given scope and hook ID. Example request:

{
  "scope": "user_activity",
  "hook_id": "prod"
}

Field explanations:

scope: The same scope you used when registering the webhook.
hook_id: The ID of the webhook you want to remove.

Example response:

{
  "success": true
}

User token

Generate a permanent token to authenticate users in the claimr widget.

GET /token

Create or retrieve a user token. If the user doesn’t exist, they’ll be registered automatically. Example request:

GET /token?account=user123&platform=discord&name=PlayerOne

Query parameters:

account: Unique identifier of the user (e.g., wallet address, email, or internal ID).
platform: Platform name associated with the account (e.g., discord, email, internal).
name: Display name for the user. If not set, defaults to the account value.

Example response:

{
  "success": true,
  "data": {
    "token": "user_token_string"
  }
}

Usage:

Production: Add the token to the data-user-token attribute in the embed script.
Development: Append it as a user_token query parameter in the widget preview URL.

User

Manage referral data, activity, and rewards.

GET /user/ref_id

Fetch a user’s referral ID and create a referral link if it doesn’t already exist. Query parameters:

account: The user’s unique identifier (email, nickname, or internal ID).
platform: The platform name (e.g., web3, email, internal).
pid: The campaign ID where the referral link should be created.

Example response:

{
  "success": true,
  "data": {
    "ref_id": "string"
  }
}

POST /user/ref_id

Set a user’s referral ID to track who referred them. Example request:

{
  "account": "string",
  "platform": "string",
  "pid": "string",
  "ref_id": "string"
}

Field explanations:

account: The referred user’s unique ID.
platform: The referred user’s platform.
pid: The campaign ID.
ref_id: The referral ID of the user who referred them.

Example response:

{
  "success": true
}

POST /user/referrer

Manually set the referrer of a user using the referrer’s account information. Example request:

{
  "account": "string",
  "platform": "string",
  "pid": "string",
  "ref_account": "string",
  "ref_platform": "string"
}

Field explanations:

account: The referred user’s ID.
platform: The referred user’s platform.
pid: The campaign ID.
ref_account: The referrer’s user ID.
ref_platform: The referrer’s platform.

Example response:

{
  "success": true
}

GET /user/activity

Fetch a full list of completed items by a user, including tasks, quests, rewards, and XP earned. Query parameters:

account: The user’s ID.
platform: The user’s platform.
pid: The campaign ID.

Example response:

{
  "success": true,
  "data": {
    "userId": "string",
    "tasks": [...],
    "quests": [...],
    "rewards": [...],
    "xp": 0
  }
}

GET /user/progress

Get a full overview of a user’s progress, including both completed and pending tasks and quests. Query parameters:

account: The user’s ID.
platform: The user’s platform.
pid: The campaign ID.
env (optional): Set to dev to preview unpublished changes.

Example response:

{
  "success": true,
  "data": {
    "userId": "string",
    "actions": [...],
    "quests": [...]
  }
}

GET /user/referrals

Return a list of users referred by a specific user and their referral impact. Query parameters:

account: The user’s ID.
platform: The user’s platform.
pid: The campaign ID.
env (optional): Use dev to preview unpublished campaign data.

Example response:

{
  "success": true,
  "data": {
    "referrals": [
      {
        "id": "string",
        "name": "string",
        "ref_xp": 0,
        "xp": 0,
        "cts": 0
      }
    ]
  }
}

GET /user/balance

Check a user’s current XP balance, including XP from tasks, referrals, and UGC. Query parameters:

account: The user’s ID.
platform: The user’s platform.
pid: The campaign ID.

Example response:

{
  "success": true,
  "data": {
    "xp": 0,
    "ref_xp": 0,
    "ugc_xp": 0
  }
}

POST /user/reward

Reward a user for an off-platform action (e.g. within your app) by adding XP to their balance. Example request:

{
  "account": "string",
  "platform": "string",
  "pid": "string",
  "id": "string",
  "xp": 100
}

Field explanations:

account: The user’s ID.
platform: The user’s platform.
pid: The campaign ID.
id: A unique identifier for this reward transaction.
xp: XP points to add to the user.

Example response:

{
  "success": true
}

POST /user/withdraw

Deduct XP points from a user’s balance (e.g. to revoke a reward). Example request:

{
  "account": "string",
  "platform": "string",
  "pid": "string",
  "id": "string",
  "xp": 50,
  "strict": true
}

Field explanations:

account: The user’s ID.
platform: The user’s platform.
pid: The campaign ID.
id: A unique identifier for the withdrawal.
xp: XP points to subtract from the user.
strict: If true, prevents the user’s balance from going negative.

Example response:

{
  "success": true
}

All information about the points for each user can be checked in Analytics. To find out more, read our article User information.

Tasks

Trigger specific actions and reward users by defining task types and their completion criteria within a campaign.

POST /action/value

Set or update a numeric attribute of a user’s action (e.g., likes, followers). Use this method to record a value for a specific user action within a campaign quest. Validates user login, campaign bundle, and quest group before executing the task. Used with API Number Value tasks. Example request:

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

Field explanations:

account: Unique user identifier (e.g., email, nickname, or internal ID).
platform: Platform the user belongs to (e.g., steam, email, web3).
pid: Campaign ID where the quest is configured.
cid: Quest ID where the action is located.
aid: Action ID to be updated.
value: Numeric value you want to assign to the user’s action.
env (optional): Use dev to target draft campaign versions.

Example response:

{
  "success": true
}

POST /stream/value

Accumulate numeric attributes associated with user actions (e.g., total transactions). Use this method to push a value to all API stream tasks within a campaign that match the specified stream name. It automatically finds and triggers all quests and tasks configured for the given stream across all campaign schemes and groups. Used with API Stream Value tasks. Example request:

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

Field explanations:

account: Unique user identifier (e.g., email, nickname, or internal ID).
platform: Platform the user belongs to (e.g., steam, email, web3).
pid: Campaign ID where the stream tasks are configured.
stream: Stream name used in the task setup.
value: Numeric value to accumulate.
env (optional): Use dev to target draft campaign versions.

Example response:

{
  "success": true
}

Events

Track custom user actions by pushing event data to claimr. Events can be used to trigger task completions based on user behavior.

POST /event

Creates a custom event record associated with a user for tracking and triggering downstream processes. Events are stored with optional categorization and custom data payload. Example request:

{
  "account": "user123",
  "platform": "steam",
  "pid": "campaign_abc123",
  "name": "level_completed",
  "id": "evt_xyz789",
  "category": "gameplay",
  "data": {
    "level": 5,
    "score": 1250,
    "completion_time": 180
  },
  "ts": 1672531200
}

Field explanations:

account: A unique identifier for the user (e.g., email, nickname, or internal user ID).
platform: Platform where the user originates (e.g., web3, steam).
pid: Campaign ID the event is associated with.
name: Name of the event (e.g., level_completed, liked_post).
id: Custom ID of the event. Can be used to track or filter it later.
category: Optional category name to group events (e.g., gameplay, transaction).
data: Custom payload with any relevant attributes (e.g., score, time, level).
ts: Client-side timestamp of when the event occurred.

Example response:

{
  "success": true
}

GET /events

Retrieves all custom events associated with a user for tracking and triggering downstream processes. Events are stored with optional categorization and custom data payload. Results can be filtered by category and name. Query parameters:

account: User account identifier.
platform: Platform identifier.
pid: Campaign ID.
name: Event name for filtering (e.g., level_completed).
category: Event category for filtering (e.g., gameplay).

Example response:

{
  "success": true,
  "events": [
    {
      "id": "evt_xyz789",
      "account": "user123",
      "platform": "steam",
      "pid": "campaign_abc123",
      "name": "level_completed",
      "category": "gameplay",
      "data": {
        "level": 5,
        "score": 1250,
        "completion_time": 180
      },
      "ts": 1672531200,
      "oid": "org_123"
    }
  ]
}

Connecting events to tasks

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

Events count task: For an “Events count” task, claimr tracks how many times an event with a specific category and name occurs. For example, if you set up a task to reward users after they achieve 10 likes, claimr counts each incoming like event via POST /event. Once the count reaches 10, the reward is automatically triggered.
User identification: claimr identifies the user associated with the event using the account and platform fields in the payload. For example, if a user logs in with Web3 (using their wallet), claimr uses the wallet address to link the event to the correct user. This ensures that points and completions are attributed accurately.

For more information about configuration, read our article on Events tasks.

Campaign

Access campaign-level data, including task structure, season progress, and participation statistics. Useful for both live and development environments.

GET /campaign/info

Returns detailed campaign information including all tasks and quests. Supports both published and development environments. Query parameters:

pid: Campaign ID to retrieve information for.
env (optional): Set to dev to fetch unpublished campaign changes.

Example response:

{
  "success": true,
  "data": {
    "id": "campaign_abc123",
    "name": "Summer Gaming Challenge",
    "actions": [
      {
        "id": "daily_login",
        "name": "Daily Login",
        "type": "api_call",
        "recurrence": "daily",
        "ref_xp": 10,
        "xp": 50,
        "xp_mul": 1.5,
        "meta": {
          "additionalProp1": {}
        },
        "deps": [
          "tutorial_completed"
        ],
        "is_optional": false
      }
    ],
    "quests": []
  }
}

GET /campaign/points

Returns campaign points and season information. Calculates season progression based on configured thresholds. Query parameters:

pid: Campaign ID to retrieve points information for.

Example response:

{
  "success": true,
  "data": {
    "id": "campaign_abc123",
    "name": "Summer Gaming Challenge",
    "total_points": 2500,
    "season_points": 350,
    "season_index": 2,
    "season": {
      "name": "Season 3: Masters",
      "max_xp": 1000
    }
  }
}

GET /campaign/stats

Returns comprehensive campaign statistics including points awarded and participation metrics. Useful for analytics and reporting. Query parameters:

pid: Campaign ID to retrieve statistics for.

Example response:

{
  "success": true,
  "data": {
    "id": "campaign_abc123",
    "name": "Summer Gaming Challenge",
    "total_points": 152000,
    "total_users": 450,
    "active_users": 320,
    "stats": {
      "stats": {
        "pcn": 152000,
        "ecn": 450,
        "acn": 320,
        "additionalProp1": "string",
        "additionalProp2": "string",
        "additionalProp3": "string"
      },
      "additionalProp1": "string",
      "additionalProp2": "string",
      "additionalProp3": "string"
    }
  }
}

Invite codes

Control access to your campaign by issuing, assigning, and managing invite codes linked to user identifiers.

GET /code

Retrieves information about an invite code, including which users have used it. Query parameters:

code: The invite code to check.
pid: Campaign/Project ID associated with the invite code.

Example request:

GET /code?code=ABC123&pid=campaign_001

Example response:

{
  "success": true,
  "data": {
    "used_by": [
      "user123",
      "user456"
    ]
  }
}

Field explanations:

used_by: An array of user identifiers who have used this invite code. If empty, the code hasn’t been used.

POST /code

Assigns an invite code to a user (identified by wallet address). This also handles user registration if the address is new, creates campaign entries, and marks the invite code as used. Example request:

{
  "code": "ABC123",
  "pid": "campaign_001",
  "used_by": "0x1234567890abcdef1234567890abcdef12345678"
}

Field explanations:

code: The invite code being claimed.
pid: The campaign ID the code belongs to.
used_by: The wallet address of the user who is using the code.

Example response:

{
  "success": true,
  "data": {}
}

DELETE /code

Releases an invite code that was previously assigned to a user, making it available again. The used_by field is optional and can be used to specify the user to remove the code from. Example request:

{
  "code": "ABC123",
  "pid": "campaign_001",
  "used_by": "0x1234567890abcdef1234567890abcdef12345678"
}

Field explanations:

code: The invite code to release.
pid: The campaign ID the code belongs to.
used_by: The user (wallet address) the code was associated with (optional).

Example response:

{
  "success": true,
  "data": {}
}

Wallets

Use these endpoints to award or withdraw XP, track referrals, and manage invite codes based on user wallet addresses. This is especially useful for blockchain-based campaigns where users interact via Web3 wallets.

GET /wallet/code

Returns the invite code used by a specific wallet. This endpoint retrieves the invite code associated with a wallet address in a specific campaign. If no code was used, the response returns an empty string. Query parameters:

address – The wallet address to check.
pid – The campaign ID.

Success response:

{
  "success": true,
  "data": {
    "code": "ABC123"
  }
}

GET /wallet/ref_id

Returns a wallet’s referral ID for a specific campaign. Use this endpoint to retrieve the referral ID generated for a wallet. If no referral was generated, or the wallet is unregistered, an error will be returned. Query parameters:

address – The wallet address.
pid – The campaign ID.

Success response:

{
  "success": true,
  "data": {
    "ref_id": "ref_abc123xyz"
  }
}

GET /wallet/referrals

Returns all referrals made by a wallet address. This endpoint lists all wallets that were referred by a specific wallet within a campaign, along with the number of points earned per referral. Query parameters:

address – The referrer’s wallet address.
pid – The campaign ID.

Success response:

{
  "success": true,
  "data": {
    "address": "0x123...",
    "points": [
      {
        "address": "0xabc...",
        "total_points": 200
      }
    ]
  }
}

POST /wallet/reward

Award XP reward to a wallet. This method assigns XP to a user’s wallet address for actions performed outside claimr. Used to register off-platform events and update the wallet balance. Request body:

{
  "address": "0x123...",
  "pid": "campaign_001",
  "id": "reward_task_001",
  "xp": 100,
  "env": "string"
}

Success response:

{
  "success": true
}

POST /wallet/withdraw

Withdraw XP points from a wallet. Use this to deduct XP from a wallet’s balance. Useful for processing point spending or reversing incorrect rewards. The strict flag determines whether to enforce a minimum balance. Request body:

{
  "address": "0x123...",
  "pid": "campaign_001",
  "id": "withdraw_payout_001",
  "xp": 100,
  "strict": true,
  "env": "string"
}

Success response:

{
  "success": true
}

Leaderboard

Track user performance and rank participants based on the points they’ve earned in your campaign. The leaderboard helps you highlight top contributors, motivate engagement, and display rankings in real time.

GET /leaderboard

Retrieve leaderboard data for a specific campaign. Supports both v1 and v2 leaderboard formats based on campaign type. The v1 format is a basic version available for all campaigns. It returns a ranked list of up to 100–150 users based on their XP. The v2 format is an advanced, unlimited version available with selected packages. It allows access to the full leaderboard. Query parameters:

pid: Campaign ID.
account: User’s account identifier (required for v2 campaigns).
platform: Account’s platform (required for v2 campaigns when account is provided).

Example response:

{
  "success": true,
  "data": {
    "live": true,
    "leaderboard": [
      {
        "rank": 1,
        "score": 1250.75,
        "user": {
          "id": "user_123",
          "name": "John Doe",
          "avatar": "https://example.com/avatar.jpg"
        }
      }
    ],
    "rank": 5
  }
}

Field explanations:

rank: The position of the user on the leaderboard.
score: The total points (XP) the user has earned.
user: User details associated with this leaderboard entry.
- id: The internal user ID.
- name: The user’s display name.
- avatar: URL to the user’s profile picture (if available).
live: Indicates if the leaderboard is actively updating.
rank (outside leaderboard array): The personal rank of the user if the account was specified.

Custom API methods and integrations

claimr offers extensive flexibility beyond its standard API methods, allowing for seamless integration with your proprietary systems. If your project requires unique data handling or custom API endpoints tailored to your specific needs, we can create these custom API methods upon request. Contact our support team to enable this advanced feature.

​Webhooks

​POST /hook

​DELETE /hook

​User token

​GET /token

​User

​GET /user/ref_id

​POST /user/ref_id

​POST /user/referrer

​GET /user/activity

​GET /user/progress

​GET /user/referrals

​GET /user/balance

​POST /user/reward

​POST /user/withdraw

​Tasks

​POST /action/value

​POST /stream/value

​Events

​POST /event

​GET /events

​Connecting events to tasks

​Campaign

​GET /campaign/info

​GET /campaign/points

​GET /campaign/stats

​Invite codes

​GET /code

​POST /code

​DELETE /code

​Wallets

​GET /wallet/code

​GET /wallet/ref_id

​GET /wallet/referrals

​POST /wallet/reward

​POST /wallet/withdraw

​Leaderboard

​GET /leaderboard

​Custom API methods and integrations

Webhooks

POST /hook

DELETE /hook

User token

GET /token

User

GET /user/ref_id

POST /user/ref_id

POST /user/referrer

GET /user/activity

GET /user/progress

GET /user/referrals

GET /user/balance

POST /user/reward

POST /user/withdraw

Tasks

POST /action/value

POST /stream/value

Events

POST /event

GET /events

Connecting events to tasks

Campaign

GET /campaign/info

GET /campaign/points

GET /campaign/stats

Invite codes

GET /code

POST /code

DELETE /code

Wallets

GET /wallet/code

GET /wallet/ref_id

GET /wallet/referrals

POST /wallet/reward

POST /wallet/withdraw

Leaderboard

GET /leaderboard

Custom API methods and integrations