Headless Tournaments Backend Integration

This requires the Server to Server API Integration, you can check how to implement it here.

Basic Concepts (Property Descriptions)

Buy In Amount: Is the amount of money a customer needs to pay to join the tournament.

Total Collected: Is the total amount of money collected. ( Number of Users * Buy In Amount )

Total Balance: Is the end result of all the money collected minus all the money rewarded to users.

Type: Currently there are 2 types of tournament rewards available:

• CASH_FIXED: Fixed cash rewards that don’t change regardless of how many users join the tournament

• CASH_PERCENTAGE: Percentage based rewards distribute a percentage of the new pool available to each tier, thus it relies on how many users join the tournament to get reward value

Title: Title or Name of the Tournament

Description: Description text to store a longer detailed description of the tournament.

Max Participants: Is the max number of participants allowed to join the tournament. If not provided, the system will infer the max number of participants based on the compliance limit set for the max reward allowed (this only applies to Percentage Based Rewards)

Max Attempts: Set this value to the number of attempts a player can have per tournament, the value is 1 by default

Min Payout Amount: Is an optional number used in Percentage Based Rewards to ensure a min Pool Net Amount before rewards.

Fee: Is a percentage used in Percentage Based Rewards to deduct a fee from the Total Collected before distributing the rewards.

Pool Net Amount: In Percentage Based Rewards, this is the amount to be distributed amongst the different reward tiers. It’s the greatest number between the MinPayoutAmount and the Total Collected minus the applied fee. ( PoolNetAmount = GREATEST( ( TC - ( TC * Fee % ) ) , MinPayout ) )

Pool Net Amount, Fee and MinPayoutAmount are ignored in CASH_FIXED type of tournaments since by the nature of the reward they have no impact, that's why they are optional.

Scoring Type: If type selected is HIGHEST_SCORE then users will be ranked first if they have the highest score and if type selected is LOWEST_SCORE then users will be ranked first if they have the lowest score (for example Golf scoring)

Game ID: Id of the type of game the tournament represents

Location Ids: IDs of physical location (used to filter tournaments by location). If no locations are set, that means the tournament is available in ALL locations

Created At: Timestamp of when the tournament was created.

Expires At: Timestamp of when the tournament will expire (not allow more joins).

Starts At: Timestamp of when the tournament starts (it won't accept scores until after this time)

Is Public: This boolean represents if the tournament is public or private one.

Private Code: This is the private code users need to provide to gain visibility on a private tournament

Metadata String: JSON string to store extra data at both the header level and at the user score level

Position: Position of the user in the ranking / leaderboard

Position Override: Value used to display a different value on the ranking. Used for example to display tied positions, you can override a 3 rd place as 2 to show a tie between position 2 and 3

Can Submit New Score: Boolean value to determine if the user can submit a new score

Create a Tournament

POST /api/rest/pool-tournament/create

{
  "apiKey": "your-Lucra-assigned-api-key", // contact account manager for details
  "object" {
    "title": "Test Tournament",
 // display name of the tournament
    "description": "Test Tournament", // (optional) extra display info of the tournament
    "fee": 5, // % to deduct from collected pool before doing the reward distribution
    "startsAt: "2024-12-10T00:00:00+00:00", // (optional) when the tournament starts accepting scores
    "expiresAt": "2024-12-31T00:00:00+00:00", // (optional) when the tournament is expected to end
    "type": "CASH_PERCENTAGE", // type of tournament, accepted values: 'CASH_FIXED' | 'CASH_PERCENTAGE'

    "buyInAmount": 10,
 // buy-in amount users must pay to join to the tournament
    "minPayoutAmount": 10,
 // (optional) min payout amount to calculate rewards
    "maxParticipants": 100, // max number of players allowed to join the tounament
    "scoringType": "HIGHEST_SCORE", // (optional) scoring style to determinate a winner, (HIGHEST_SCORE or LOWEST_SCORE)
    "gameId": "SOME_ID", // (optional) ID of pre-approved games
    "locationId": "uuid-string", // (optional) ID of a location (used to filter tournaments by location)    
    "paymentStructure": [
      {
        "position": 1, // Place in the ranking
        "value": 80 // If type is CASH_PERCENTAGE this value means the % of the pool to be received, if it's CASH_FIXED then it means the fixed amount of the price
      },
      {
        "position": 2, // Place in the ranking
        "value": 20 // If type is CASH_PERCENTAGE this value means the % of the pool to be received, if it's CASH_FIXED then it means the fixed amount of the price
      }
    ],
    
    "metadataString": "{}"  // JSON string with optional custom metadata
  }
}

Retrieve Existing Tournament Info

Returns the data related a specific tournament ID.

GET /api/rest/pool-tournament/:matchupId?apiKey=your-Lucra-assigned-api-key

{
  "matchup": {
    "id": "64c744cf-c837-422b-9da7-ff3a359525df", // ID of the matchup record
    "type": "CASH_PERCENTAGE",
    "status": "CLOSED",
    "tenantId": "SAMPLE",
    "createdAt": "2025-01-17T20:28:20.339716+00:00",
    "expiresAt": "2025-01-31T20:00:00.000000+00:00",
    "startsAt": "2025-01-20T20:00:00.000000+00:00",
    "isPublic": true,
    "gameId": "AIR-HOCKEY",
    "title": "Awesome Tournament",
    "description": "The most Awesome Tournament",
    "metadataString": "{ \"someProperty\": 123 }",
    "locationIds": [
      "2f2d279b-6149-40a7-9f6d-38d9cbea23cd", 
      "ef01589e-c9ac-4214-846a-39648eccfbb9"
    ],
    "fee": 5,
    "buyInAmount": 10,
    "numberOfParticipants": 3,
    "maxParticipants": 250,
    "maxAttempts": 3,
    "poolNetAmount": 28.5,
    "scoringType": "HIGHEST_SCORE", // or LOWEST_SCORE,
    "privateCode": "PV6485",
    "rewardStructure": [
      {
        "position": 1,
        "positionOverride": null,
        "value": 100,
        "userId": "33e35526-410c-4517-81c3-2162cde5c786",
        "userName": "DivineTarantula",
        "tierNetAmount": 28.5
      }
    ],
    "users": [
      {
        "userId": "33e35526-410c-4517-81c3-2162cde5c786",
        "userName": "DivineTarantula",
        "userAvatarUrl": "https://api.lucrasports.com/assets/some-path-to-img",
        "position": 1,
        "positionOverride": null,
        "metadataString": "{}",
        "score": 580,
        "rewardNetAmount": 28.5,
        "canSubmitNewScore": false
      },
      {
        "userId": "13c7a90f-76c8-401e-afee-f7d81d8e4420",
        "userName": "FunnyBoar",
        "userAvatarUrl": "https://api.lucrasports.com/assets/some-path-to-img",
        "position": 2,
        "positionOverride": null,
        "metadataString": "{}",
        "score": 570,
        "rewardNetAmount": 0,
        "canSubmitNewScore": false,
      },
      {
        "userId": "a0116f41-cbd3-4d84-b445-8228baf3d908",
        "userName": "SpareWasp",
        "userAvatarUrl": "https://api.lucrasports.com/assets/some-path-to-img",
        "position": 3,
        "positionOverride": null,
        "metadataString": "{}",
        "score": 550,
        "rewardNetAmount": 0,
        "canSubmitNewScore": true
      }
    ]
  }
}

Update an Existing Tournament

Completes a tournament setting the final reward structure and type

PUT | PATCH /api/rest/pool-tournament/${matchupId}

{
  "apiKey": "your-Lucra-assigned-api-key", // contact account manager for details
  "object" {
    "title": "Test Tournament",
 // display name of the tournament
    "description": "Test Tournament", // (optional) extra display info of the tournament
    "startsAt: "2024-12-10T00:00:00+00:00", // (optional) when the tournament starts accepting scores
    "expiresAt": "2024-12-31T00:00:00+00:00", // (optional) when the tournament is expected to end
    "type": "CASH_PERCENTAGE", // type of tournament, accepted values: 'CASH_FIXED' | 'CASH_PERCENTAGE'
    "buyInAmount": 10,
 // (optional) buy-in amount users must pay to join to the tournament
    "minPayoutAmount": 10,
 // (optional) min payout amount to calculate rewards
    "maxParticipants": 100, // max number of players allowed to join the tounament
    "fee": 5, // (optional) % to deduct from collected pool before doing the reward distribution
    "scoringType": "HIGHEST_SCORE", // (optional) scoring style to determinate a winner, (HIGHEST_SCORE or LOWEST_SCORE)
    "gameId": "SOME_ID", // (optional) ID of pre-approved games
    "locationId": "uuid-string", // (optional) ID of a location (used to filter tournaments by location)    
    "paymentStructure": [
      {
        "position": 1, // Place in the ranking
        "value": 80 // If type is CASH_PERCENTAGE this value means the % of the pool to be received, if it's CASH_FIXED then it means the fixed amount of the price
      },
      {
        "position": 2, // Place in the ranking
        "value": 20 // If type is CASH_PERCENTAGE this value means the % of the pool to be received, if it's CASH_FIXED then it means the fixed amount of the price
      }
    ],
    
    "metadataString": "{}"  // JSON string with optional custom metadata
  }
}

Update Users Scores

Update the scores of the users inside a tournament. Can be called with the full list of users or with only the users that need to be updated. Scores can be updated more than once per user during the lifespan of the tournament If the attemptFinished property is passed as true, then the user round will be marked as finished and it will no longer accept new updates (it will fail the request). This is also a requirement to the Replay functionality to allow players to join a tournament more than once, it enables the Join action once again. If it's passed as false it will just update the first available/open score attempt and it will not prevent further updates If, no round complete logic can be implemented, a way to disable this attempt complete check is to pass the omitAttemptCompletedCheck when creating the tournament, thus ignoring the closure of the attempt when a Player tries to join again (this is useful when the scoring attempt logic is fully controlled on the tenant side)

See user.canSubmitNewScore to determine if a user can have a new score submited

PUT | PATCH /api/rest/pool-tournament/${matchupId}/users-scores

{
  "apiKey": "your-Lucra-assigned-api-key", // contact account manager for details
  "object" {
    "userScores": [
      {
        "userId": "user-uuid-string"
        "score": 100, // integer with the score of the user (can be negative)
        "metadataString": "{}",  // JSON string with optional custom metadata
        "attemptFinished": true, // Marks the end of this user round (optional)
      }
    ]
  }
}

Complete an Existing Tournament

Completes a tournament setting the final reward structure and type

POST /api/rest/pool-tournament/${matchupId}/complete

{
  "apiKey": "your-Lucra-assigned-api-key", // contact account manager for details
  "object" {
    "type": "CASH_PERCENTAGE", // type of tournament, accepted values: 'CASH_FIXED' | 'CASH_PERCENTAGE'
    "minPayoutAmount": 10,
 // min payout amount to calculate rewards  
    "paymentStructure": [
      {
        "position": 1, // Place in the ranking
        "value": 80, // If type is CASH_PERCENTAGE this value means the % of the pool to be received, if it's CASH_FIXED then it means the fixed amount of the price
        "userId": "user-uuid-string" // winner of the reward
      },
      {
        "position": 2, // Place in the ranking
        "value": 20, // If type is CASH_PERCENTAGE this value means the % of the pool to be received, if it's CASH_FIXED then it means the fixed amount of the price
        "userId": "user-uuid-string" // winner of the reward
      }
    ],
    
    "metadataString": "{}"  // JSON string with optional custom metadata
    
    // optional
    "title": "Test Tournament",
 // display name of the tournament
    "description": "Test Tournament", // extra display info of the tournament    
  }
}

Cancel an Existing Tournament

Cancels an existing tournament.

POST /api/rest/pool-tournament/:matchupId/cancel?apiKey=your-Lucra-assigned-api-key

Query Active Tournaments

Queries open tournaments with pagination and filters. Accepted params:

• limit: max number of returned records (optional)

• offset: skip N number of records (optional)

• locationId: location ID to get records for tournaments that match that ID or that belong to all locations (optional)

• userId: if provided, it will return only the tournaments the user is participating, It will not include Closed ones (optional)

GET /api/rest/pool-tournament/query/active?apiKey=your-Lucra-assigned-api-key

{
    "result": {
        // this 4 will return the same vales as the one provided or default if applicable
        "limit": 50,
        "offset": 0,
        "locationId": "ccc728ce-ed1d-42f5-9c4b-bdcbe50bec81",
        "userId": "0d8bcf16-99ea-4f58-8d0c-32ffb3965e99",
        "records": [
            {
                "id": "1ce740f2-e7d5-495b-a015-f7019e443685",
                "status": "PENDING",
                // same properties as the the Retrieve Existing Info response
            }
        ]
    }
}