Gameball Developers Guide
v4.0
v4.0
  • Introduction
  • Installing Gameball
    • Web
      • Initialize Gameball Customer Widget
      • Track Customer Events
      • Track Orders & Cashback Reward
      • Integrate Redemption
      • Track Referrals
      • Go-Live Checklist
    • iOS
      • Getting Started
      • Initialize Gameball Customer Profile
      • Track Customer Events
      • Track Orders & Cashback Reward
      • Integrate Redemption
      • Push Notifications
      • Track Referrals
      • Go-Live Checklist
    • Android
      • Getting Started
      • Initialize Gameball Customer Profile
      • Track Customer Events
      • Track Orders & Cashback Reward
      • Integrate Redemption
      • Push Notifications
      • Go-Live Checklist
    • React Native
      • Getting Started
      • Initialize Gameball Customer Profile
      • Track Customer Events
      • Track Orders & Cashback Reward
      • Integrate Redemption
      • Track Referrals
      • Push Notifications
      • Go-Live Checklist
    • Flutter
      • Getting Started
      • Initialize Gameball Customer Profile
      • Track Customer Events
      • Track Orders & Cashback Reward
      • Integrate Redemption
      • Track Referrals
      • Go-Live Checklist
    • Generic Mobile App
      • Initialize Gameball Customer Profile
      • Track Customer Events
      • Track Orders & Cashback Reward
      • Integrate Redemption
      • Track Referrals
      • Push Notifications
  • REST API
    • Overview
      • What's New in V4.0
      • Authentication
      • Rate Limiting
      • Status and Error Codes
    • Customers
      • Customer Management
      • Customer Progress
      • Customer Tags
      • Customer Notifications
    • Events
    • Order
      • Order Tracking
      • Order Rewards & History
    • Payment
      • Payment Tracking
    • Transactions
      • Cashback & Redemptions
      • Hold Management
      • Transaction Management
      • Transaction Validation
    • Coupons
    • Configurations
      • Reward Configurations
      • Program Configurations
      • Widget Configuration
    • Leaderboard
    • Batches
      • Batch Creation
      • Batch Management
  • Webhooks
    • Overview
    • Subscribing to Webhooks
    • Webhook Topics
      • Customer's Notifications
      • Customer's Profile Updates
  • Tutorials
    • Tracking Customer Events
    • Redemption Integration
      • Direct debit redemption
      • Coupons Redemption
        • Use Your Own Couponing Engine
        • Gameball Couponing Engine
    • Checkout Integration
    • Build Custom UI Elements
      • Reward Campaigns
      • VIP Tiers
      • Customer Balance
      • Widget Configurations
      • Coupons Customer Experience
      • Customer Notifications
      • Customer Leaderboard
    • Build your Own Notification System
    • Channel Merging Guide
    • Previewing Potential Points Before Purchase
    • Refund
    • Retail & POS Integration with Gameball Loyalty Program
    • Referrals
    • Widget Deep Links
    • Batch APIs usage example
  • Branch.io Integration
  • Adjust Integration
Powered by GitBook
On this page
  • GET - Customers Leaderboard
  • Request
  • Response
  1. REST API

Leaderboard

Encourage customer engagement by displaying a gamified leaderboard on your website or mobile app. Use the Leaderboard API to showcase top-performing customers and motivate further interaction.

PreviousWidget ConfigurationNextBatches

Last updated 6 months ago

Available APIs


GET - Customers Leaderboard

https://api.gameball.co/api/v4/integrations/leaderboard

This API retrieves the leaderboard rankings of customers within your loyalty program in Gameball, either for a specific date range or for all time. Results are ordered from the highest to the lowest rank, displaying each customer’s rank, progress, and tier details.

Security: Requires apikey and secretkey headers.

Request

Query Parameters

from datetime Optional The start date of the leaderboard range. If not provided, the leaderboard shows all-time data.


to datetime Optional The end date of the leaderboard range. If not provided, the leaderboard shows all-time data.


customerId string Optional Unique identifier for the customer that you can reference across the customer’s whole lifetime. It is used to get the rank of this customer in the leaderboard.


rewardCampaignId integer Optional Filter leaderboard results based on a specific reward campaign.


customerTag string Optional Filter results by customers who are tagged with a specific tag.


rewardCampaignTag string Optional Filter leaderboard results by reward campaign tags.


Response

application/json

leaderboard array An array of customers ranked on the leaderboard, sorted by their score. Each entry in the array includes details about each customer, providing a comprehensive overview of their standing within the entire customer base.

Leaderboard Object

displayName string The display name of the customer on the leaderboard.


customerId string Unique identifier for the customer that you can reference across the customer’s whole lifetime.


progress number The progress made by the customer, such as points earned.


rank number The customer’s position on the leaderboard, determined by their performance, such as points accumulated. The rank is typically higher for those with more points or progress.


tierName string The name of the customer’s current tier.


tierIcon string URL for the icon representing the customer’s current tier.


customerRank number The position of the requested customer on the leaderboard, reflecting their rank relative to all other customers in your entire customer base. A lower rank number (e.g., 1) indicates a higher standing, typically based on points or achievements.


customersCount number The total number of customers on the leaderboard.


Sample Response

{
  "leaderboard": [
    {
      "displayName": "John Doe",
      "customerId": "cust_12345",
      "progress": 2500,
      "rank": 1,
      "tierName": "Gold",
      "tierIcon": "https://cdn.gameball.co/uploads/gb-library/levels-icons/level-a1.webp"
    },
    {
      "displayName": "Jane Smith",
      "customerId": "cust_67890",
      "progress": 1800,
      "rank": 2,
      "tierName": "Silver",
      "tierIcon": "https://cdn.gameball.co/uploads/gb-library/levels-icons/level-a2.webp"
    }
  ],
  "customerRank": 1,
  "customersCount": 100
}

Customer Leaderboard