Skip to main content
This feature is only available with paid plans. Contact us to know more.
The Tournaments API lets you create and manage tournaments on top of our existing game catalog, pull live leaderboard data while a tournament is running, and fetch final results once it ends. There are 5 APIs, all under /v2/tournaments:

​
Tournaments vs real-time multiplayer games

Tournaments are different from our real-time multiplayer games offering: If you want head-to-head matches between small groups of players, use real-time multiplayer games. If you want time-bound, leaderboard-based competitions open to all your users, use Tournaments.

​
How a tournament works

Here’s the typical lifecycle of a tournament:
1

Create the tournament

Use the Create Tournament API to schedule a tournament on an eligible game. You get back a tournament_id.
2

Get the game link

Use the List Tournaments API to fetch the tournament’s details, including the playable game.url. This URL already includes the tournament_id query parameter.
3

Send users to the tournament

Open the game.url for your users, appending a puid query parameter identifying each user. For example:
The game URL must contain both the tournament_id (already included in the game.url we return) and puid query parameters for the game to record scores against the tournament correctly. Scores made without these parameters, or outside the tournament window, do not count towards the tournament.
4

Show live rankings

While the tournament is live, use the Live Leaderboard API to display current rankings to your users — including any specific player’s rank.
5

Fetch final results

Once the tournament ends, use the Final Results API to get the final ranked list — for instance, to distribute rewards to winners.

​
Game eligibility

Tournaments are only available on score-based games. Games are referenced using the same game_code values (the code field) that you receive from the All Games API.
Not all games in your catalog are eligible for tournaments. Ask your Gamezop Account Manager for the list of eligible games enabled for your account.

​
Authentication

All requests require a Bearer token in the Authorization header. Tokens are scoped per partner and control which games and tournaments you can access.
You can find the Bearer token for these APIs under Settings & Admin > API Tokens within the Gamezop Business Dashboard.

​
Tournament lifecycle

A tournament is always in one of 3 states:

​
General conventions

​
Ranking logic

Leaderboard and results rankings are determined as follows:
  1. Higher score wins.
  2. Tied scores: the score achieved earlier wins.
  3. Still tied: the lexicographically smaller puid wins.
Ranks are 1-indexed.

​
Rate limits

The Live Leaderboard and Final Results limits are counted per tournament, not per token. If you fan out to many users, fetch once into your own backend or CDN and serve from there. Do not proxy every end-user request straight through.

​
Idempotency

The Create Tournament API requires an Idempotency-Key header — a unique string per request. Retrying a request with the same key returns the original response instead of creating a duplicate tournament. Keys are retained for 10 minutes and are scoped per token.