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

Basic Settings
Timing
Prize Pool
Multi-Entry Configuration

{
  "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.

{
  "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 amount
distribution: 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 functionality
rebuy_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
`scheduled`	Tournament created, waiting for start time	Update, Cancel, View
`open`	Registration open, tournament not started	Update, Cancel, Register Players
`in_progress`	Tournament actively running	View, Register Players (if allowed)
`completed`	Tournament finished, results available	View Results
`cancelled`	Tournament 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 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

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

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.

External APIs

Events & Webhooks

Tournament Management

Tournament Management

Overview

Tournament Creation

Scheduled Tournament Creation

Tournament Configuration Options

Tournament Monitoring

Get Tournament Status

Tournament Status Values

List Tournaments

Tournament Updates

Update Tournament Configuration

Updateable Fields by Status

Tournament Cancellation

Cancel Tournament

Cancellation Policies

Advanced Tournament Management

Tournament Templates

Bulk Operations

Error Handling

Common Error Responses

Invalid Tournament Configuration

Tournament Not Found

Insufficient Permissions

Best Practices

Validation

Error Handling

Monitoring

Testing

Next Steps

Player Management

Results & Leaderboards

​Tournament Management

​Overview

​Tournament Creation

​Scheduled Tournament Creation

​Tournament Configuration Options

​Tournament Monitoring

​Get Tournament Status

​Tournament Status Values

​List Tournaments

​Tournament Updates

​Update Tournament Configuration

​Updateable Fields by Status

​Tournament Cancellation

​Cancel Tournament

​Cancellation Policies

​Advanced Tournament Management

​Tournament Templates

​Bulk Operations

​Error Handling

​Common Error Responses

​Invalid Tournament Configuration

​Tournament Not Found

​Insufficient Permissions

​Best Practices

Validation

Error Handling

Monitoring

Testing

​Next Steps

Player Management

Results & Leaderboards

Tournament Management

Overview

Tournament Creation

Scheduled Tournament Creation

Tournament Configuration Options

Tournament Monitoring

Get Tournament Status

Tournament Status Values

List Tournaments

Tournament Updates

Update Tournament Configuration

Updateable Fields by Status

Tournament Cancellation

Cancel Tournament

Cancellation Policies

Advanced Tournament Management

Tournament Templates

Bulk Operations

Error Handling

Common Error Responses

Invalid Tournament Configuration

Tournament Not Found

Insufficient Permissions

Best Practices

Next Steps