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.

Available APIs

• Customer Leaderboard

---

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
}

---