Get Leaderboard

Get Leaderboard

Draft Feature

Important: This API is currently in draft and not ready for implementation. It will be released soon.

Retrieve tournament leaderboard with player rankings sorted by points in descending order.

Endpoint

GET /tournaments/:version/leaderboard

Path Parameters

Parameter Type Description
version Integer API version number

Query Parameters

Parameter Type Required Description
player_id String No Filter by specific player ID
brand_id Integer No Filter by specific brand ID
tournament_id String No Filter by specific tournament ID
tournament_status String No Filter by tournament status: 0=Pending, 1=Active, 2=Complete, 3=Inactive
tournament_end_date_from String No Filter tournaments ending from this date (format: YYYY-MM-DD)
tournament_end_date_to String No Filter tournaments ending until this date (format: YYYY-MM-DD)
format String No Response format (e.g., csv) - TBD
page Integer No Page number for pagination
page_size Integer No Number of items per page
require_totals Boolean No Whether to include total counts in response
Default Date Range

Note: When searching by brand + player without specifying date filters, only leaderboards from the last 3 months are returned by default.

Filter Application Rules

Note: Status and date filters (tournament_status, tournament_end_date_from, tournament_end_date_to) are only applied when searching by brand + player. If only tournament_id is provided, these filters are ignored and only pagination parameters (page, page_size) are respected.

Tournament ID Validation

Important: If a tournament_id is provided along with brand + player filters, and the tournament does not match the other filter criteria (status, date range, etc.), the API will return an error indicating that the tournament does not exist.

Response Format

Player + Brand + Tournament + format

Sorting

Results are automatically sorted by points in descending order (highest points first).

Pagination

This endpoint supports pagination for efficient data retrieval.

Example Request

curl --location 'https://stgsinatragateway.groovegaming.com/tournaments/1/leaderboard?brand_id=3435&player_id=217850&tournament_status=1&tournament_end_date_from=2025-01-01&tournament_end_date_to=2025-12-31&page=1&page_size=10' \
--header 'Authorization: Bearer bm9mYXJAZ21haWwuY29tOmRkZA=='

Request URL Parameters

  • 1 - API version in the URL path
  • brand_id=3435 - Filter by brand ID (optional)
  • player_id=217850 - Filter by player ID (optional)
  • tournament_status=1 - Filter for Active tournaments (optional)
  • tournament_end_date_from=2025-01-01 - Filter tournaments ending from this date (optional)
  • tournament_end_date_to=2025-12-31 - Filter tournaments ending until this date (optional)
  • page=1 - First page (optional)
  • page_size=10 - 10 items per page (optional)

Response

Example Response

{
    "total": 3,
    "data": [
        {
            "tournament_id": "2eab1af5-81e7-4d85-ad2e-fd4a23fae68a",
            "brand_id": 3435,
            "player_id": "217850",
            "start_multiplier": 1,
            "multiplier": 1,
            "eligible": true,
            "points": 250,
            "position": 1,
            "total_bets": 1001,
            "total_wins": 500.5,
            "total_rounds": 1,
            "created_at": "2025-09-22T14:08:00Z"
        },
        {
            "tournament_id": "2eab1af5-81e7-4d85-ad2e-fd4a23fae68a",
            "brand_id": 3435,
            "player_id": "217849",
            "start_multiplier": 1,
            "multiplier": 1,
            "eligible": true,
            "points": 140,
            "position": 2,
            "total_bets": 601.5,
            "total_wins": 200.5,
            "total_rounds": 1,
            "created_at": "2025-09-22T14:08:00Z"
        },
        {
            "tournament_id": "2eab1af5-81e7-4d85-ad2e-fd4a23fae68a",
            "brand_id": 3435,
            "player_id": "217848",
            "start_multiplier": 1,
            "multiplier": 1,
            "eligible": true,
            "points": 22,
            "position": 3,
            "total_bets": 102.5,
            "total_wins": 20.5,
            "total_rounds": 1,
            "created_at": "2025-09-22T14:08:00Z"
        }
    ],
    "message": ""
}

Response Fields

Field Type Description
total Integer Total number of players in the leaderboard (used for pagination)
data Array Array of leaderboard entry objects sorted by points (highest first)
message String Additional message or error information (empty on success)

Leaderboard Entry Fields

Field Type Description
tournament_id String (UUID) Unique identifier of the tournament this entry belongs to
brand_id Integer Brand identifier where the player is registered
player_id String Unique identifier of the player in the leaderboard
start_multiplier Number Initial multiplier value when player joined the tournament
multiplier Number Current multiplier applied to the player’s points
eligible Boolean Whether the player is eligible for prizes (true=eligible, false=ineligible)
points Integer Total points earned by the player in the tournament
position Integer Player’s current ranking position in the leaderboard (1=first place)
total_bets Number Total amount of bets placed by the player in the tournament
total_wins Number Total amount of wins earned by the player in the tournament
total_rounds Integer Total number of game rounds played by the player in the tournament
created_at String Timestamp when the player joined the tournament (ISO 8601 format)

Key Features

  • Automatic Sorting: Results are automatically sorted by points in descending order (highest points first)
  • Player + Brand + Tournament Format: Each entry represents a unique combination of player, brand, and tournament
  • Eligibility Tracking: The eligible field indicates whether players qualify for prizes
  • Multiplier Support: Both starting and current multipliers are tracked for each player
  • Point Precision: Points are tracked as integers for accurate leaderboard positioning

Authentication

Authorization Required

This endpoint requires Bearer token authentication using your Sinatra back office credentials. All requests must include a valid Authorization header. Unauthorized requests will be rejected.

Required Header:

Authorization: Bearer <base64_encoded_credentials>

Token Generation:

base64_encoded_credentials = base64encode(sinatrauser:sinatrapassword)

Example:

  • Sinatra Username: myuser@example.com
  • Sinatra Password: mypassword
  • Credentials String: myuser@example.com:mypassword
  • Base64 Encoded: bXl1c2VyQGV4YW1wbGUuY29tOm15cGFzc3dvcmQ=
  • Final Header: Authorization: Bearer bXl1c2VyQGV4YW1wbGUuY29tOm15cGFzc3dvcmQ=

Replace with your actual Sinatra back office credentials.

Use Cases

  • Display tournament rankings to players
  • Show leaderboard on tournament pages
  • Track player performance across tournaments
  • Generate tournament reports