Skip to main content

​
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 times
  • Monitor real-time tournament status and player counts
  • Update tournament configurations and settings
  • Cancel tournaments when necessary
  • List 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 tournament
  • game: Game type identifier
  • max_players: Maximum participant limit (optional - null for unlimited)
  • min_players: Minimum players to start
  • entry_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.

​
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

StatusDescriptionAvailable Actions
scheduledTournament created, waiting for start timeUpdate, Cancel, View
openRegistration open, tournament not startedUpdate, Cancel, Register Players
in_progressTournament actively runningView, Register Players (if allowed)
completedTournament finished, results availableView Results
cancelledTournament cancelled before completionView

​
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 status
  • gameSlug - Filter by game type
  • startDate - Filter tournaments starting after date
  • endDate - Filter tournaments starting before date
  • limit - 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

Full Control - All fields can be updated:
  • Tournament name and description
  • Start/end times
  • Player limits and entry fees
  • Prize pool configuration
  • Registration windows

​
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 refunds
  • notifyPlayers - 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 time
  • In-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 rebuys
  • During Play: Partial refunds based on tournament progress
  • After 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.