Sign in

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

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

Changed in 4 of the 38 revisions of this API.15

  • e7c26fe8697a3See the full diff
    • ○

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

      api-security-added

    • ○

      the endpoint scheme security apiKey was removed from the API

      api-security-removed

    • ○

      the endpoint scheme security secretKey was removed from the API

      api-security-removed

  • 7887186517671See the full diff
    • ○

      removed the non-success response with the status 400

      response-non-success-status-removed

  • 95e7f65e5afd1See the full diff
    • ○

      endpoint added

      endpoint-added

  • 919eb7a392aa1See the full diff
    • ▲

      api path removed without deprecation

      api-path-removed-without-deprecation

    This revision also has 38 changes that name no endpoint, such as unreferenced schemas being removed. See the revision's changelog