Sign in

v36

latestOpenAPI 3.1.0raw.githubusercontent.com2026-08-017439390.7 KB

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.

get/api/v4.0/integrations/leaderboard

Query parameters

fromstring date-time

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

tostring date-time

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

customerIdstring

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.

rewardCampaignIdinteger

Filter leaderboard results based on a specific reward campaign.

customerTagstring

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

rewardCampaignTagstring

Filter leaderboard results by reward campaign tags.

Response

Leaderboard retrieved successfully

customerRanknumber

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.

customersCountnumber

The total number of customers on the leaderboard.

Example 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"
    }
  ],
  "customerRank": 1,
  "customersCount": 100
}