Skip to main content
GET
/
api
/
v4.0
/
integrations
/
leaderboard
cURL
curl --request GET \
  --url https://api.gameball.co/api/v4.0/integrations/leaderboard \
  --header 'apikey: <api-key>' \
  --header 'secretkey: <api-key>'
{
  "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
}

​
Customer 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 header.

Authorizations

​
apikey
string
header
required
​
secretkey
string
header
required

Query Parameters

​
from
string<date-time>

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

​
to
string<date-time>

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

​
customerId
string

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

Filter leaderboard results based on a specific reward campaign.

​
customerTag
string

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

​
rewardCampaignTag
string

Filter leaderboard results by reward campaign tags.

Response

200 - application/json

Leaderboard retrieved successfully

​
leaderboard
object[]

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.

​
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.

Example:

1

​
customersCount
number

The total number of customers on the leaderboard.

Example:

100