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

Query Parameters

from

string<date-time>

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

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.

Show child attributes

leaderboard.displayName

string

The display name of the customer on the leaderboard.

Example:

"John Doe"

leaderboard.customerId

string

Unique identifier for the customer that you can reference across the customer's whole lifetime.

Example:

"cust_12345"

leaderboard.progress

number

The progress made by the customer, such as points earned.

Example:

2500

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

Example:

1

leaderboard.tierName

string

The name of the customer's current tier.

Example:

"Gold"

leaderboard.tierIcon

string

URL for the icon representing the customer's current tier.

Example:

"https://cdn.gameball.co/uploads/gb-library/levels-icons/level-a1.webp"

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

API documentation

Webhooks

Customer Leaderboard