> ## Documentation Index
> Fetch the complete documentation index at: https://docs.platform.gamezop.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Run tournaments on Gamezop games

> Use the Gamezop Tournaments API to create and manage time-bound tournaments on our games, pull live leaderboard data, and fetch final results.

<Note>
  This feature is only available with paid plans. [Contact us](https://business.gamezop.com/contact-us/enquire-now) to know more.
</Note>

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`:

| API                                                                                 | When to use                                          |
| :---------------------------------------------------------------------------------- | :--------------------------------------------------- |
| [Create Tournament API](/publishers/gamezop/advanced/tournaments/create-tournament) | Create a new tournament                              |
| [List Tournaments API](/publishers/gamezop/advanced/tournaments/list-tournaments)   | List all tournaments accessible to your token        |
| [Live Leaderboard API](/publishers/gamezop/advanced/tournaments/live-leaderboard)   | Live rankings during an active tournament            |
| [Final Results API](/publishers/gamezop/advanced/tournaments/final-results)         | Final rankings after a tournament ends               |
| [Delete Tournament API](/publishers/gamezop/advanced/tournaments/delete-tournament) | Delete a not-yet-started tournament created in error |

***

## Tournaments vs real-time multiplayer games

Tournaments are different from our [real-time multiplayer games](/publishers/gamezop/advanced/multiplayer-games) offering:

|             | Tournaments                                                                                             | Real-time multiplayer games                                                  |
| :---------- | :------------------------------------------------------------------------------------------------------ | :--------------------------------------------------------------------------- |
| **Format**  | Users play individually and compete for the top spots on a leaderboard                                  | 2 to 5 players are matched together and play against each other in real time |
| **Window**  | A defined tournament window (`starts_at` to `ends_at`) during which users play and set their high score | Each match starts when players are matched, and ends when the match is over  |
| **Outcome** | A ranked leaderboard of high scores across all participants                                             | Winners of that specific match                                               |

If you want head-to-head matches between small groups of players, use [real-time multiplayer games](/publishers/gamezop/advanced/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:

<Steps>
  <Step title="Create the tournament">
    Use the [Create Tournament API](/publishers/gamezop/advanced/tournaments/create-tournament) to schedule a tournament on an eligible game. You get back a `tournament_id`.
  </Step>

  <Step title="Get the game link">
    Use the [List Tournaments API](/publishers/gamezop/advanced/tournaments/list-tournaments) to fetch the tournament's details, including the playable `game.url`. This URL already includes the `tournament_id` query parameter.
  </Step>

  <Step title="Send users to the tournament">
    Open the `game.url` for your users, appending a `puid` query parameter identifying each user. For example:

    ```text theme={null}
    https://www.gamezop.com/g/B1MfIa4QCg?lang=en&tournament_id=tour_01HZZ2S9GQK6Y3V2S8D7A9F2BC&puid=player_123
    ```

    <Warning>
      **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.
    </Warning>
  </Step>

  <Step title="Show live rankings">
    While the tournament is `live`, use the [Live Leaderboard API](/publishers/gamezop/advanced/tournaments/live-leaderboard) to display current rankings to your users — including any specific player's rank.
  </Step>

  <Step title="Fetch final results">
    Once the tournament ends, use the [Final Results API](/publishers/gamezop/advanced/tournaments/final-results) to get the final ranked list — for instance, to distribute rewards to winners.
  </Step>
</Steps>

***

## 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](/publishers/gamezop/types-of-integration/all-games-api).

<Info>
  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.
</Info>

***

## 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.

```text theme={null}
Authorization: Bearer <your_access_token>
```

You can find the Bearer token for these APIs under *Settings & Admin > API Tokens* within the [Gamezop Business Dashboard](https://dashboard.gamezop.com).

***

## Tournament lifecycle

A tournament is always in one of 3 states:

| Status   | Meaning                                                                                                                                          |
| :------- | :----------------------------------------------------------------------------------------------------------------------------------------------- |
| `future` | The tournament has been created but has not started yet. This is the only state in which it can be deleted.                                      |
| `live`   | The tournament is in progress. The [Live Leaderboard API](/publishers/gamezop/advanced/tournaments/live-leaderboard) is available in this state. |
| `past`   | The tournament has ended. The [Final Results API](/publishers/gamezop/advanced/tournaments/final-results) is available in this state.            |

***

## General conventions

| Convention          | Details                                                                                                                                                                                                      |
| :------------------ | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Base URL            | `https://api.gamezop.com`                                                                                                                                                                                    |
| Timestamps          | All timestamps are UTC, in ISO 8601 format (e.g. `2026-06-01T10:00:00Z`)                                                                                                                                     |
| Player identifier   | `puid` is the unique identifier for each of your players. You append it to the game URL when sending users to a tournament, and it identifies players in leaderboard and results data                        |
| Game identifier     | `game_code` (e.g. `B1MfIa4QCg`) is used throughout these APIs. This is the `code` value from the [All Games API](/publishers/gamezop/types-of-integration/all-games-api)                                     |
| Tournament duration | Minimum 300 seconds (5 minutes), maximum 259200 seconds (3 days)                                                                                                                                             |
| Scheduling          | A tournament's `starts_at` must be in the future, and no more than 15 days from the time of creation                                                                                                         |
| Scoring window      | Only scores achieved during the tournament window count: `starts_at <= score_time < ends_at`                                                                                                                 |
| Localization        | The `lang` query parameter (optional, default `en`) is accepted on the List Tournaments API. Game name and playable URL are returned in the requested language where available, with English as the fallback |

***

## 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

| API                   | Limit      | Scope          |
| :-------------------- | :--------- | :------------- |
| Create Tournament API | Standard   | Per token      |
| List Tournaments API  | 10 / min   | Per token      |
| Live Leaderboard API  | 1200 / min | Per tournament |
| Final Results API     | 24 / 24h   | Per tournament |
| Delete Tournament API | Standard   | Per token      |

<Warning>
  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.
</Warning>

***

## Idempotency

The [Create Tournament API](/publishers/gamezop/advanced/tournaments/create-tournament) 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.

***