Skip to main content
GET
cURL

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.
The Leaderboard API is part of the Advanced leaderboard. It needs the Advanced leaderboard plan feature, on your plan or as an add-on, and an active subscription. The Normal leaderboard does not include it.
Rankings are based on net totals: refunds and cancellations are taken off the period of the original purchase, and transactions blocked as fraud never count. Customers are ranked by your levels method (amount spent, points, orders, referrals, or score), and customers with the same result always appear in the same order.
  • Each request returns up to 50 rows.
  • Use from and to for custom date ranges. The range must start within the last 62 days.
  • Filter by customerTag, rewardCampaignId, or rewardCampaignTag.
  • The leaderboard ranks 1,000 customers by default, up to 10,000.
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