Tournament Management The Tournament Management APIs enable casino operators to create, manage, and monitor tournaments across both scheduled and hop-on/off formats using external APIs.
Overview Tournament Management provides complete lifecycle control over tournaments:
Create scheduled tournaments with specific start timesMonitor real-time tournament status and player countsUpdate tournament configurations and settingsCancel tournaments when necessaryList and filter tournaments across your operator account
Permission Required : tournaments.write for create/update/delete operations, tournaments.read for viewing tournaments.
Tournament Creation Scheduled Tournament Creation Create tournaments that start at a specific scheduled time:
POST /api/tournaments Authorization : Bearer {your-api-key} Content-Type : application/json { "name" : "Test Tournament" , "external_id" : "EXT_001" , "game" : "crash-classic" , "scheduled_start" : "2024-01-15T20:00:00Z" , "max_players" : 50 , "min_players" : 5 , "entry_fee" : 10.50 , "prize_pool" : { "total" : 500 , "distribution" : { "1" : 50 , "2" : 30 , "3" : 20 } }, "config" : { "tournament_type" : "points_based" } }
Response: { "tournament_id" : "12345" , "status" : "scheduled" , "estimated_prize_pool" : 500 , "tournament" : { "id" : "12345" , "name" : "Test Tournament" , "operator_id" : "op_123" , "status" : "scheduled" , "games" : [ { "slug" : "crash-classic" , "config" : {}, "status" : "active" } ] } }
Tournament Configuration Options { "name" : "Tournament Name" , "game" : "crash-classic" , "max_players" : 100 , "min_players" : 5 , "entry_fee" : 10.00 }
name : Display name for the tournamentgame : Game type identifiermax_players : Maximum participant limit (optional - null for unlimited)min_players : Minimum players to startentry_fee : Cost to join tournament Unlimited Capacity : Set max_players to null for tournaments with no participant limit. This is useful for hop-on/off style tournaments.
{ "scheduled_start" : "2024-01-15T20:00:00Z" }
scheduled_start : When tournament is scheduled to begin The tournament platform handles registration timing automatically based on the tournament status and configuration.
{ "prize_pool" : { "total" : 500 , "distribution" : { "1" : 50 , "2" : 30 , "3" : 20 } } }
total : Total prize pool amountdistribution : Prize distribution by position (percentages) Example : With 100 entry fee and above distribution:
1st place: 50% of total = $250
2nd place: 30% of total = $150
3rd place: 20% of total = $100
These fields are set at the tournament level and control the rebuy system: { "max_entries_per_player" : 3 , "rebuy_enabled" : true , "rebuy_fee" : 20.00 }
max_entries_per_player : Maximum total entries per player (includes initial entry)rebuy_enabled : Enable multi-entry functionalityrebuy_fee : Cost per additional entry beyond the first Rebuy settings are validated when tournaments are created. Players can only rebuy during active tournament phases.
Tournament Monitoring Get Tournament Status Monitor tournament progress and current state:
GET /api/tournaments/12345/status Authorization : Bearer {your-api-key}
Response: { "tournamentId" : "12345" , "status" : "in_progress" , "currentPlayers" : 87 , "maxPlayers" : 100 , "startTime" : "2024-01-15T20:00:00Z" , "actualStartTime" : "2024-01-15T20:02:15Z" , "estimatedEndTime" : "2024-01-15T21:15:00Z" , "currentRound" : 3 , "totalRounds" : 5 , "registrationStatus" : "closed" , "prizePool" : { "totalAmount" : 870.00 , "currency" : "USD" }, "gameRoom" : { "roomId" : "room_abc123" , "activeConnections" : 87 } }
Tournament Status Values Status Description Available Actions scheduledTournament created, waiting for start time Update, Cancel, View openRegistration open, tournament not started Update, Cancel, Register Players in_progressTournament actively running View, Register Players (if allowed) completedTournament finished, results available View Results cancelledTournament cancelled before completion View
List Tournaments Retrieve tournaments with filtering and pagination:
GET /api/tournaments?status=in_progress&limit=20&offset=0 Authorization : Bearer {your-api-key}
Query Parameters:
status - Filter by tournament statusgameSlug - Filter by game typestartDate - Filter tournaments starting after dateendDate - Filter tournaments starting before datelimit - Number of results per page (default: 50, max: 100)offset - Pagination offset
Response: { "tournaments" : [ { "tournamentId" : "12345" , "name" : "Daily Championship" , "status" : "in_progress" , "startTime" : "2024-01-15T20:00:00Z" , "currentPlayers" : 87 , "maxPlayers" : 100 , "prizePool" : 870.00 } ], "pagination" : { "total" : 156 , "limit" : 20 , "offset" : 0 , "hasMore" : true } }
Tournament Updates Update Tournament Configuration Modify tournament settings before or during play:
PUT /api/tournaments/12345 Authorization : Bearer {your-api-key} Content-Type : application/json { "name" : "Updated Championship Name" , "maxPlayers" : 120 , "registrationCloses" : "2024-01-15T19:45:00Z" }
Update Restrictions : Some fields cannot be modified once the tournament has started. Check the response for any validation errors.
Updateable Fields by Status Scheduled Status
Open Status
In Progress
Full Control - All fields can be updated:
Tournament name and description
Start/end times
Player limits and entry fees
Prize pool configuration
Registration windows
Limited Updates - Registration active:
Tournament name and description
Maximum players (can only increase)
Registration close time (can extend)
Prize pool (can only increase)
Minimal Updates - Tournament running:
Tournament name and description only
No timing or configuration changes
Tournament Cancellation Cancel Tournament Cancel a tournament before or during play:
DELETE /api/tournaments/12345 Authorization : Bearer {your-api-key} Content-Type : application/json { "reason" : "Insufficient players" , "refundPlayers" : true , "notifyPlayers" : true }
Parameters:
reason - Reason for cancellation (for audit logs)refundPlayers - Whether to process player refundsnotifyPlayers - Send cancellation notifications
Response: { "tournamentId" : "12345" , "status" : "cancelled" , "cancelledAt" : "2024-01-15T19:45:00Z" , "reason" : "Insufficient players" , "playersRefunded" : 15 , "refundAmount" : 150.00 }
Cancellation Policies Tournament cancellation triggers automatic refund processing for all registered players and sends webhook notifications to your system.
Cancellation Rules:
Scheduled Tournaments : Can be cancelled before start timeIn-Progress Tournaments : Can be cancelled during active play (NEW)Completed Tournaments : Cannot be cancelled (results are final)
Refund Processing:
Before Start : Full refunds for all entry fees and rebuysDuring Play : Partial refunds based on tournament progressAfter Completion : No refunds (tournament results stand)
Advanced Tournament Management Tournament Templates Create reusable tournament templates for common configurations:
POST /api/tournament-templates Authorization : Bearer {your-api-key} Content-Type : application/json { "name" : "Daily Championship Template" , "gameSlug" : "crash-classic" , "maxPlayers" : 100 , "entryFee" : 10.00 , "prizePool" : { "type" : "percentage" , "distribution" : [ 50 , 30 , 20 ] }, "rebuyEnabled" : true }
Bulk Operations Create multiple tournaments from templates:
POST /api/tournaments/bulk Authorization : Bearer {your-api-key} Content-Type : application/json { "templateId" : "template_123" , "schedule" : [ { "startTime" : "2024-01-15T20:00:00Z" , "name" : "Monday Championship" }, { "startTime" : "2024-01-16T20:00:00Z" , "name" : "Tuesday Championship" } ] }
Error Handling Common Error Responses Invalid Tournament Configuration { "error" : "validation_failed" , "message" : "Tournament configuration is invalid" , "details" : { "startTime" : "Start time must be in the future" , "maxPlayers" : "Maximum players must be greater than minimum players" } }
Tournament Not Found { "error" : "tournament_not_found" , "message" : "Tournament with ID 12345 not found" , "tournamentId" : "12345" }
Insufficient Permissions { "error" : "insufficient_permissions" , "message" : "API key lacks required permissions" , "required" : "tournaments.write" , "provided" : [ "tournaments.read" ] }
Best Practices
Validation
Validate all input parameters before API calls
Check tournament status before attempting updates
Verify player limits and timing constraints
Error Handling
Implement proper error handling for all status codes
Use exponential backoff for retries
Log errors for debugging and monitoring
Monitoring
Monitor tournament status regularly
Set up alerts for tournament failures
Track player registration patterns
Testing
Test tournament creation in sandbox environment
Verify cancellation and refund workflows
Load test player registration flows
Next Steps
Player Management Learn how to register and manage players in your tournaments.
Results & Leaderboards Access real-time rankings and final tournament results.
