Changed on

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

Request

  • Base URL: https://api.gameball.co
  • URL: https://api.gameball.co/api/v4.0/integrations/leaderboard
  • Auth: API key in header apikey and API key in header secretkey

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
}

Changes

  • e7c26fe8697aRevision changes
    • info

      the endpoint scheme security apiKey AND secretKey was added to the API

    • info

      the endpoint scheme security apiKey was removed from the API

    • info

      the endpoint scheme security secretKey was removed from the API

  • 788718651767Revision changes
    • info

      removed the non-success response with the status