> ## Documentation Index
> Fetch the complete documentation index at: https://docs.gameball.co/llms.txt
> Use this file to discover all available pages before exploring further.

# Customer Leaderboard

> Retrieve leaderboard rankings of customers within your loyalty program in Gameball, either for a specific date range or for all time.

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

<Info>
  **Security:** Requires **apikey** header.
</Info>


## OpenAPI

````yaml GET /api/v4.0/integrations/leaderboard
openapi: 3.1.0
info:
  title: Gameball API
  description: >-
    Gameball REST API v4.0 - Complete API reference for integrating loyalty,
    gamification, and customer engagement features
  version: 4.0.0
servers:
  - url: https://api.gameball.co
security:
  - bearerAuth: []
paths:
  /api/v4.0/integrations/leaderboard:
    get:
      description: >-
        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.
      parameters:
        - name: from
          in: query
          description: >-
            The start date of the leaderboard range. If not provided, the
            leaderboard shows all-time data.
          required: false
          schema:
            type: string
            format: date-time
        - name: to
          in: query
          description: >-
            The end date of the leaderboard range. If not provided, the
            leaderboard shows all-time data.
          required: false
          schema:
            type: string
            format: date-time
        - name: customerId
          in: query
          description: >-
            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.
          required: false
          schema:
            type: string
        - name: rewardCampaignId
          in: query
          description: Filter leaderboard results based on a specific reward campaign.
          required: false
          schema:
            type: integer
        - name: customerTag
          in: query
          description: Filter results by customers who are tagged with a specific tag.
          required: false
          schema:
            type: string
        - name: rewardCampaignTag
          in: query
          description: Filter leaderboard results by reward campaign tags.
          required: false
          schema:
            type: string
      responses:
        '200':
          description: Leaderboard retrieved successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  leaderboard:
                    type: array
                    description: >-
                      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.
                    items:
                      type: object
                      properties:
                        displayName:
                          type: string
                          description: The display name of the customer on the leaderboard.
                          example: John Doe
                        customerId:
                          type: string
                          description: >-
                            Unique identifier for the customer that you can
                            reference across the customer's whole lifetime.
                          example: cust_12345
                        progress:
                          type: number
                          description: >-
                            The progress made by the customer, such as points
                            earned.
                          example: 2500
                        rank:
                          type: number
                          description: >-
                            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
                        tierName:
                          type: string
                          description: The name of the customer's current tier.
                          example: Gold
                        tierIcon:
                          type: string
                          description: >-
                            URL for the icon representing the customer's current
                            tier.
                          example: >-
                            https://cdn.gameball.co/uploads/gb-library/levels-icons/level-a1.webp
                  customerRank:
                    type: number
                    description: >-
                      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:
                    type: number
                    description: The total number of customers on the leaderboard.
                    example: 100
      security:
        - apiKey: []
          secretKey: []
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
    apiKey:
      type: apiKey
      in: header
      name: apikey
    secretKey:
      type: apiKey
      in: header
      name: secretkey

````