White-Label/Matchmaking Engine
Pro Feature

Skill-based matchmaking for your platform

A full white-label matchmaking engine delivered as an API. Configure the algorithm, set region preferences, enable team play, and receive real-time match events — without building any of the infrastructure yourself.

Who is this for?

The Matchmaking Engine is built for developers who need to pair players fairly and quickly without reinventing ranked-queue infrastructure.

Indie game developers

Ship ranked online play for your game without maintaining matchmaking servers or writing Glicko-2 from scratch.

Esports platform builders

Power competitive queues for multiple disciplines from a single integration. Configure separate rating pools and region rules per game mode.

Community platforms

Add casual or rated matchmaking to chess clubs, card game communities, or any game where fair pairing matters.

How a match flows

Every match follows a predictable state machine your client can poll or subscribe to via webhooks.

1

Player joins the queue

status: searching

Call POST /matchmaking/queue with the player key, discipline, and optional region or team members. The engine starts searching immediately.

2

Engine proposes a match

status: proposed

When a suitable opponent is found, both queue entries move to "proposed" and a match record is created. Poll the queue entry or listen on the match.proposed webhook.

3

Players accept

status: active

Each player calls POST /accept with their player key. When require_both_accept is false, the first accept activates the match immediately.

4

Match confirmed (game started)

status: in_progressoptional

When require_confirm is enabled, call POST /confirm once the game client has launched. This sets started_at and moves the match to in_progress — ensuring your result endpoint only accepts real game data.

5

Result submitted

status: completed

Either participant calls POST /result with home and away scores. Ratings update instantly for rated matches and a canonical match record is created.

Matching algorithms

Choose the algorithm that fits your game's pairing needs. Switch at any time via the config API.

elo_band

ELO Band

Pairs players whose ratings fall within a configurable band. The band expands over time as the player waits, ensuring everyone eventually finds a game. Simple, predictable, and great for games where raw skill parity is the only goal.

hybrid

Hybrid Composite Score

Computes a weighted score across skill proximity, region match quality, and wait time. Fully configurable weights let you tune whether latency or rating accuracy matters more. The acceptance threshold decays as players wait, preventing endless queues.

Team matchmaking

Set team_size in your config to enable team queues. The captain submits the queue entry with a team_members array. Team MMR is the mean of all member ratings; team RD uses a quadrature mean so combined uncertainty is correctly reflected. Matched teams see a single match record with home and away rosters.

// POST /matchmaking/queue — team entry
{
  "player_key": "captain_xyz",
  "player_name": "Captain",
  "discipline": "chess",
  "team_id": "team_alpha",
  "team_members": [
    { "player_key": "member_001", "player_name": "Member One" }
  ]
}

Captain is always seat 1

The player_key on the queue entry is the captain. team_members contains the remaining seats — length must equal team_size minus one.

No duplicates

The captain key must not appear in team_members. All member keys must be unique within the entry.

Up to 10 per side

team_size can be set to any integer from 1 (solo) to 10. Teams of 1 are valid and behave identically to a solo queue.

Endpoints

15 endpoints covering the full match lifecycle, configuration, and event delivery.

Queue

POST/matchmaking/queue
GET/matchmaking/queue
GET/matchmaking/queue/{entry_id}
DELETE/matchmaking/queue/{entry_id}

Matches

GET/matchmaking/matches
GET/matchmaking/matches/{match_id}
POST/matchmaking/matches/{match_id}/accept
POST/matchmaking/matches/{match_id}/confirm
POST/matchmaking/matches/{match_id}/result

Configuration

GET/matchmaking/config
PUT/matchmaking/config

Webhooks

GET/matchmaking/webhooks
POST/matchmaking/webhooks
DELETE/matchmaking/webhooks/{webhook_id}

Configuration reference

Manage your integration config via GET/PUT /matchmaking/config. Changes take effect on the next matchmaking cycle.

algorithm

"elo_band" or "hybrid". Determines how candidate pairs are scored and whether they cross the acceptance threshold.

team_size

Players per team including the captain. Set to 1 for solo queues. Maximum 10. Requires Pro tier for values above 1.

require_confirm

When true, a matched game must be explicitly confirmed via POST /confirm before results can be submitted. Use this to gate result submission on a real game starting.

require_both_accept

When true, both players must accept before the match activates. When false, the first accept immediately starts the clock. Useful for auto-accept flows.

expose_opponent_name

When false, the opponent's name and team roster are redacted in the match resource until the game starts. Prevents pre-game targeting or stalking.

accept_timeout

Seconds a player has to accept before the match expires and both players return to searching. Defaults to 30 seconds.

Real-time events via webhooks

Register a URL to receive POST requests whenever a match state changes. Each event is signed with HMAC-SHA256 using your webhook secret so you can verify authenticity.

match.proposedmatch.acceptedmatch.completedmatch.expired

Machine-readable schema

All matchmaking endpoints are included in the OpenAPI 3.1 spec. Generate a typed client in any language or import directly into Postman.

/api/external/v1/openapi.json

Available on the Pro plan

The Matchmaking Engine is included with the Pro plan. Team queues (team_size > 1) and the hybrid algorithm require Pro tier. All other matchmaking features including solo queues, ELO band pairing, webhooks, and config management are included.

View pricing plans
Start Pro trialExplore the Tournament API