Chapter 6

Tournaments

Tournaments

Draft Feature

Important: This feature is currently in draft and not ready for implementation. It will be released soon. Please do not attempt to integrate these APIs until official release notification.

The Tournaments feature provides operators with comprehensive tournament management capabilities, including tournament listing, leaderboard access, and player ranking systems.

Tournament Configuration

Tournaments are configured and managed through the Sinatra back office. All tournament settings, rules, and parameters must be set up there before they can be accessed via these APIs.

Authorization Required

All tournament API requests must be authorized using the Authorization header with a Bearer token generated from your Sinatra credentials. Unauthorized requests will be rejected.

Token Format:

Authorization: Bearer <base64_encoded_credentials>

Token Generation:

base64_encoded_credentials = base64encode(sinatrauser:sinatrapassword)

Replace sinatrauser and sinatrapassword with your actual Sinatra back office credentials.

Available APIs

Key Features

  • Tournament Management: Filter and retrieve tournaments by operator, brand, provider, and status
  • Advanced Filtering: Search by game IDs, game names, and tournament names
  • Leaderboard System: Player rankings sorted by points in descending order
  • Prize Distribution: Automated prize distribution to tournament winners
  • Pagination Support: Efficient data retrieval with configurable page sizes
  • Multi-format Support: Player + Brand + Tournament format combinations

Subsections of Tournaments

Get Tournaments

Get Tournaments

Draft Feature

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

Retrieve a list of tournaments with comprehensive filtering options.

Endpoint

GET .../tournaments

Request Parameters

Parameter Type Description
Operator Drop-down Filter by operator
Brand Drop-down Filter by brand
Provider Drop-down Filter by provider
Game ID’s / Game Name Text input Filter by specific game identifiers or names
Tournament Status Drop-down Filter by status: 0=Pending, 1=Active, 2=Complete, 3=Inactive
Tournament Name Text input Filter by tournament name

Pagination

This endpoint supports pagination for efficient data retrieval.

Parameter Type Description
page Integer Page number (starting from 1)
page_size Integer Number of items per page

Example Request

curl --location 'https://stgsinatragateway.groovegaming.com/tournaments/1/?page=1&page_size=10&status=0&operators=6&brands=55' \
--header 'Authorization: Bearer bm9mYXJAZ21haWwuY29tOmRkZA=='

Request URL Parameters

  • page=1 - First page
  • page_size=10 - 10 items per page
  • status=0 - Tournament status filter (0=Pending)
  • operators=6 - Operator ID filter
  • brands=55 - Brand ID filter

Response

Example Response

{
    "total": 3,
    "data": [
        {
            "auto_win": true,
            "created_at": "2025-09-15T07:58:44Z",
            "created_by": 27687,
            "end_date": "2025-11-11 09:23:00",
            "multiplier": 1.5,
            "operator_brand_config": {
                "6": {
                    "brands": [
                        "55"
                    ]
                }
            },
            "operator_template_id": "EXT-123456",
            "participation_scope": 0,
            "prize_type": 1,
            "prizes": {
                "SpecificPositionPrize": [
                    {
                        "position": 1,
                        "prize": 200
                    },
                    {
                        "position": 2,
                        "prize": 100
                    },
                    {
                        "position": 3,
                        "prize": 50
                    }
                ]
            },
            "providers": {
                "26": {
                    "games": [
                        "82685"
                    ]
                }
            },
            "result_url": "https://example.com/tournament/result",
            "rules": {
                "BetToPointsConversion": [
                    {
                        "points_to_add": 5,
                        "required_wager": 50
                    }
                ],
                "MinimumBetAmount": [
                    {
                        "required_wager": 10
                    }
                ],
                "MinimumBetsOrRoundsRequired": [
                    {
                        "required_bets": 10,
                        "required_rounds": 1
                    }
                ],
                "WinToPointsConversion": [
                    {
                        "points_to_add": 10,
                        "required_win": 100
                    }
                ]
            },
            "start_date": "2025-11-09 08:23:00",
            "status": 2,
            "tournament_id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
            "tournament_name": "tournament test version 11",
            "updated_at": "2025-09-15T08:09:40Z",
            "updated_by": 27687
        },
        {
            "auto_win": true,
            "created_at": "2025-09-14T19:13:04Z",
            "created_by": 3,
            "end_date": "2025-10-11 09:23:00",
            "multiplier": 1.5,
            "operator_brand_config": {
                "6": {
                    "brands": [
                        "55"
                    ]
                }
            },
            "operator_template_id": "EXT-123456",
            "participation_scope": 0,
            "prize_type": 1,
            "prizes": {
                "SpecificPositionPrize": [
                    {
                        "position": 1,
                        "prize": 200
                    },
                    {
                        "position": 2,
                        "prize": 100
                    },
                    {
                        "position": 3,
                        "prize": 50
                    }
                ]
            },
            "providers": {
                "26": {
                    "games": [
                        "82685"
                    ]
                }
            },
            "result_url": "https://example.com/tournament/result",
            "rules": {
                "BetToPointsConversion": [
                    {
                        "points_to_add": 5,
                        "required_wager": 50
                    }
                ],
                "MinimumBetAmount": [
                    {
                        "required_wager": 10
                    }
                ],
                "MinimumBetsOrRoundsRequired": [
                    {
                        "required_bets": 10,
                        "required_rounds": 1
                    }
                ],
                "WinToPointsConversion": [
                    {
                        "points_to_add": 10,
                        "required_win": 100
                    }
                ]
            },
            "start_date": "2025-10-09 08:23:00",
            "status": 2,
            "tournament_id": "6ba7b810-9dad-11d1-80b4-00c04fd430c8",
            "tournament_name": "avi ac11",
            "updated_at": "2025-09-15T08:13:07Z",
            "updated_by": 27687
        },
        {
            "auto_win": true,
            "created_at": "2025-09-01T07:09:44Z",
            "created_by": 27687,
            "end_date": "2025-09-11 09:24:00",
            "multiplier": 1.5,
            "operator_brand_config": {
                "6": {
                    "brands": [
                        "55"
                    ]
                }
            },
            "operator_template_id": "EXT-123456",
            "participation_scope": 0,
            "prize_type": 1,
            "prizes": {
                "SpecificPositionPrize": [
                    {
                        "position": 1,
                        "prize": 200
                    },
                    {
                        "position": 2,
                        "prize": 100
                    },
                    {
                        "position": 3,
                        "prize": 50
                    }
                ]
            },
            "providers": {
                "26": {
                    "games": [
                        "82685"
                    ]
                }
            },
            "result_url": "https://example.com/tournament/result",
            "rules": {
                "BetToPointsConversion": [
                    {
                        "points_to_add": 5,
                        "required_wager": 50
                    }
                ],
                "MinimumBetAmount": [
                    {
                        "required_wager": 10
                    }
                ],
                "MinimumBetsOrRoundsRequired": [
                    {
                        "required_bets": 10,
                        "required_rounds": 1
                    }
                ],
                "WinToPointsConversion": [
                    {
                        "points_to_add": 10,
                        "required_win": 100
                    }
                ]
            },
            "start_date": "2025-09-09 08:23:00",
            "status": 2,
            "tournament_id": "550e8400-e29b-41d4-a716-446655440000",
            "tournament_name": "tournament test version 11",
            "updated_at": "2025-09-01T07:13:09Z",
            "updated_by": 27687
        }
    ],
    "message": ""
}

Response Fields

Field Type Description
total Integer Total number of tournaments available (used for pagination)
data Array Array of tournament objects
message String Additional message or error information (empty on success)

Tournament Object Fields

Field Type Description
tournament_id String (UUID) Unique identifier for the tournament
tournament_name String Display name of the tournament
status Integer Tournament status: 0=Pending, 1=Active, 2=Complete, 3=Inactive
start_date String Tournament start date and time (YYYY-MM-DD HH:MM:SS)
end_date String Tournament end date and time (YYYY-MM-DD HH:MM:SS)
auto_win Boolean Whether auto-win is enabled for this tournament
multiplier Number Point multiplier applied to tournament scoring
participation_scope Integer Defines who can participate (0=All players, other values for restrictions)
prize_type Integer Type of prizes awarded (1=Specific position prizes)
operator_template_id String External template identifier for the operator
result_url String URL endpoint for tournament results
created_at String Tournament creation timestamp (ISO 8601 format)
updated_at String Last update timestamp (ISO 8601 format)
created_by Integer User ID who created the tournament
updated_by Integer User ID who last updated the tournament

Complex Object Fields

operator_brand_config

Defines which operators and brands can participate in the tournament.

{
    "6": {          // Operator ID
        "brands": [
            "55"    // Array of brand IDs under this operator
        ]
    }
}

providers

Specifies which game providers and specific games are included.

{
    "26": {         // Provider ID
        "games": [
            "82685" // Array of game IDs from this provider
        ]
    }
}

prizes

Defines the prize structure for tournament winners.

{
    "SpecificPositionPrize": [
        {
            "position": 1,    // Leaderboard position
            "prize": 200      // Prize amount for this position
        }
    ]
}

rules

Tournament rules that define how players earn points and participation requirements.

Rule Type Description
BetToPointsConversion Points awarded based on wager amounts
WinToPointsConversion Points awarded based on win amounts
MinimumBetAmount Minimum wager required to participate
MinimumBetsOrRoundsRequired Minimum number of bets/rounds required

BetToPointsConversion Example:

{
    "points_to_add": 5,      // Points awarded
    "required_wager": 50     // Wager amount needed to earn these points
}

WinToPointsConversion Example:

{
    "points_to_add": 10,     // Points awarded
    "required_win": 100      // Win amount needed to earn these points
}

MinimumBetAmount Example:

{
    "required_wager": 10     // Minimum bet amount to participate
}

MinimumBetsOrRoundsRequired Example:

{
    "required_bets": 10,     // Minimum number of bets required
    "required_rounds": 1     // Minimum number of rounds required
}

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.

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

Tournament Prize

Tournament Prize Distribution

Draft Feature

Important: This feature is currently in draft and not ready for implementation. It will be released soon. Please do not attempt to integrate these APIs until official release notification.

Info

The Tournament Prize API is used to distribute prizes to winners when a tournament concludes. This endpoint handles the prize allocation from Groove to the casino operator.

Overview

When a tournament ends and winners are determined, Groove sends Tournament Prize requests to the casino operator to distribute the prizes. The casino processes these requests by validating the tournament details, checking for duplicates, and updating the player’s balance accordingly.

Warning

**Important:** Tournament Prize requests implement idempotency controls. This means the same prize request should only be processed once. If a duplicate request is received, the system must return the original response with status code 200 and the "Success - Duplicate" status.

Flow Diagram

sequenceDiagram participant Groove as Groove Platform participant Casino as Casino Operator participant Player as Player Account Groove->>Casino: Tournament Prize Request Casino->>Casino: Validate Signature Casino->>Casino: Check Idempotency Casino->>Casino: Validate Tournament ID Casino->>Casino: Validate Player ID Casino->>Casino: Process Prize alt Prize Type: Amount Casino->>Player: Credit Prize Amount else Prize Type: Other Casino->>Casino: Process Non-Monetary Prize end Casino->>Groove: Prize Response

Casino Responsibilities

The casino platform must perform the following operations when processing a Tournament Prize request:

  1. Signature Validation

    • Validate the X-Groove-Signature header
    • Calculate signature using the request body (instead of query parameters)
    • Reject the request if signature validation fails

  2. Idempotency Check

    • Check if a request with the same transaction_id has been processed before
    • If duplicate, return the original response with status “Success - Duplicate”

  3. Tournament Validation

    • Verify the tournament exists and is valid
    • Confirm the player participated in the tournament
    • Validate prize details match tournament configuration

  4. Prize Processing

    • For monetary prizes (prize_type = 1): Credit the prize amount to player’s balance
    • For non-monetary prizes (prize_type = 2): Process according to operator’s implementation
    • Store transaction details for auditing

Request Details

Endpoint

The casino URL can be either:

  1. The URL specified in the tournament definition
  2. If the tournament URL is empty, use the default wallet endpoint URL (same as regular game play)

{casino_URL}?request=tournamentWin

Request Method

POST

Request Headers

Header Required Description
X-Groove-Signature Yes Signature calculated using the request body instead of query parameters
Content-Type Yes Application/json

Request Body Parameters

Parameter Data Type Required Description
tournament_id String(UUID) Yes Unique tournament identifier
Example: 123456-13456-123456-123456
transaction_id String(255) Yes Unique transaction identifier
Example: 123123
tournament_start_date DateTime Yes Tournament start date and time
Format: YYYY-MM-DD HH:MM:SS
tournament_end_date DateTime Yes Tournament end date and time
Format: YYYY-MM-DD HH:MM:SS
tournament_position Integer Yes Player’s final position in the tournament
Example: 1 (for first place)
template_id Integer Yes Template ID defined on tournament configuration
Example: 1
prize_type Integer Yes Prize type:
1 - Monetary amount
2 - Other (non-monetary)
player_id Integer Yes Player’s unique identifier
Example: 12345
casino_id Integer Yes Casino/Brand identifier
Example: 12345
prize_value Decimal(32,10) No Prize amount (nullable for non-monetary prizes)
Example: 100.50
total_rounds Integer Yes Total number of rounds played in the tournament
Example: 10
total_bets Decimal(32,10) Yes Total amount wagered during the tournament
Example: 100
total_wins Decimal(32,10) Yes Total amount won during the tournament
Example: 2
timestamp DateTime Yes Request timestamp
Format: YYYY-MM-DD HH:MM:SS

Example Request

POST {casino_URL}?request=tournamentWin
Content-Type: application/json
X-Groove-Signature: f6d980dfe7866b6676e6565ccca239f527979d702106233bb6f72a654931b3bc

{
  "tournament_id":         "123456-13456-123456-123456",
  "transaction_id":        "123123",
  "tournament_start_date": "2025-08-27 00:00:00",
  "tournament_end_date":   "2025-08-27 00:00:00",
  "tournament_position":   1,
  "template_id":           1,
  "prize_type":            1,
  "player_id":             12345,
  "casino_id":             12345,
  "prize_value":           100.50,
  "total_rounds":          10,
  "total_bets":            100,
  "total_wins":            2,
  "timestamp":             "2025-08-27 00:00:00"
}

Response Details

Response Parameters

Parameter Data Type Required Description
transaction_id String(UUID) Yes Unique transaction identifier
Example: 11111-11111-11111-11111
code Integer Yes Response code (see below)
Example: 200
status String Yes Response status message
Example: Success - Duplicate
timestamp DateTime Yes Response timestamp
Format: YYYY-MM-DD HH:MM:SS

Example Success Response

{
  "transaction_id": "11111-11111-11111-11111",
  "code": 200,
  "status": "Success",
  "timestamp": "2025-08-27 00:00:00"
}

Example Duplicate Response

{
  "transaction_id": "11111-11111-11111-11111",
  "code": 200,
  "status": "Success - Duplicate",
  "timestamp": "2025-08-27 00:00:00"
}

Response Codes

Success Codes

Code Status Description
200 Success Prize successfully processed
200 Success - Duplicate Prize already processed (idempotent response)

Error Codes

Code Status Description
1 Internal Error Internal server error or general processing error
110 Operation not allowed Operation not permitted for various reasons:
• Invalid tournament
• Player not eligible
• Invalid prize details
• Account restrictions
Tip

Error codes follow the same standard as other transaction endpoints. For additional error codes that may apply, refer to [Appendix A: Transaction Response Status Codes](/appendix-a-transaction-response-status-codes/).

Implementation Notes

  1. Idempotency Handling:

    • Always store transaction IDs to identify duplicate requests
    • Return the original response for duplicate transactions with the same transaction ID
    • Maintain prize distribution records for auditing

  2. Signature Validation:

    • Unlike other endpoints that use query parameters, tournament prize uses the request body for signature calculation
    • Calculate signature using the entire JSON request body as a string
    • See Signature Validation for detailed implementation

  3. Prize Processing:

    • Monetary prizes should be credited to the player’s real balance
    • Non-monetary prizes require custom implementation based on operator requirements
    • Always validate prize amounts match tournament configuration

  4. Error Handling:

    • Return appropriate error codes based on validation results
    • Log all prize distribution attempts for auditing purposes
    • Include detailed error messages for troubleshooting

Security

Signature Calculation

For tournament prize requests, the signature is calculated differently than other endpoints:

  1. Use the entire request body JSON as a string (not query parameters)
  2. Append the security key to the JSON string
  3. Calculate SHA256 hash of the combined string
  4. Include hash in the X-Groove-Signature header

Signature Example

For the request body:

{
  "tournament_id": "123456-13456-123456-123456",
  "transaction_id": "123123",
  "tournament_start_date": "2025-08-27 00:00:00",
  "tournament_end_date": "2025-08-27 00:00:00",
  "tournament_position": 1,
  "template_id": 1,
  "prize_type": 1,
  "player_id": 12345,
  "casino_id": 12345,
  "prize_value": 100.50,
  "total_rounds": 10,
  "total_bets": 100,
  "total_wins": 2,
  "timestamp": "2025-08-27 00:00:00"
}

With security key "test_key", calculate:

  1. Take the exact JSON string (minified, no extra spaces)
  2. Append the security key
  3. Calculate SHA256 hash
  4. Result: X-Groove-Signature: [calculated_hash]