> For the complete documentation index, see [llms.txt](https://docs.platform.gamezop.com/publishers/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.platform.gamezop.com/publishers/gamezop/advanced/multiplayer-games/receive-winners-data.md).

# Receive data on match winners

You need to build an API endpoint for this to work:

* [Create Match API](#create-match-api)

And then to receive data on the match winners, you can use either or both of the following options:

* [Receive Winners API](#receive-winners-api) (webhook created by you where we push data)
* [Gamezop Get Match Result API](#gamezop-get-match-result-api) (Gamezop API endpoint from which you can pull data for any match)

***

### Create Match API

You will have to give us a POST API endpoint where we will send the user objects and the `room_id` when our servers group players into a match. Once we are able to find a match honouring the details you send in the `roomDetails` object, we will make a request to this endpoint, and you will have to return a `match_id`.\
\
Here's the difference between a `room_id` and a `match_id`. Let's say Alice and Bob are playing a Tic Tac Toe game in room `ABC01`. Alice wins. Now both Alice and Bob see an option to play again. They do so and now Bob wins. In this manner, players with the same `room_id` may play the game multiple times. While the `room_id` will remain same each time, the winners may differ across matches. That is why winners are scoped against a `match_id` and not against a `room_id`.

#### Your API endpoint

<mark style="color:green;">`POST`</mark> `https://api.publisher-xyz.com/games/create-match`

You must build and maintain this endpoint. This receives user-objects from Gamezop, and returns a unique `match_id`.

#### Headers

<table><thead><tr><th width="189.984375">Name</th><th width="149.63671875">Type</th><th>Description</th></tr></thead><tbody><tr><td>Authorization: Bearer</td><td>String</td><td>We can add in a bearer token in the authorization headers if you require us to.</td></tr></tbody></table>

#### Request body

<table><thead><tr><th width="190.44140625">Name</th><th width="149.859375">Type</th><th>Description</th></tr></thead><tbody><tr><td>room_id<mark style="color:red;">*</mark></td><td>String</td><td><code>roomId</code> passed by you in the encoded <code>roomDetails</code> object</td></tr><tr><td>status<mark style="color:red;">*</mark></td><td>String</td><td>One of 2 options will be passed: <code>MATCH_FOUND</code> or <a data-footnote-ref href="#user-content-fn-1"><code>NO_MATCH_FOUND</code>.</a></td></tr><tr><td>players<mark style="color:red;">*</mark></td><td>String</td><td>Array of <a data-footnote-ref href="#user-content-fn-2"><code>sub</code> values</a> matched together.</td></tr></tbody></table>

#### HTTP response codes

{% tabs %}
{% tab title="200: OK" %}
You must respond with a 200 when you return a `match_id`

Expected response body:

```json
    {
       "success": true,
       "match_id": "XYZ_match_number_1" // empty in case NO_MATCH_FOUND
    }
```

{% endtab %}
{% endtabs %}

{% hint style="info" %}
**Note for partners charging an entry fee to users**

If you are charging an entry fee, then in case of the `MATCH_FOUND` status, check buy-in validity again for all users in the request body before generating a `match_id`.&#x20;

If any player has not paid to join that match, then refund the entry fees charged to all other players and do not return a `match_id`. We will show a "No match found" screen to the user in this case.

When we send you a `NO_MATCH_FOUND` status, then you should refund the entry fee charged, if any, for the users in the request body.
{% endhint %}

***

### Receive Winners API

This will be another POST API endpoint that you create where, at the end of each match, we will send the user objects along with their ranks and scores back to your system.\
\
If you need to reward a player or take any other action on the basis of this data, you can do so upon receiving our hit on this endpoint.

#### Your API endpoint

<mark style="color:green;">`POST`</mark> `https://api.publisher-xyz.com/games/receive-winners`

You must build and maintain this endpoint. Gamezop posts data on match winners to your system at the end of each multiplayer match via this endpoint.

#### Headers

<table><thead><tr><th width="189.87109375">Name</th><th width="150.171875">Type</th><th>Description</th></tr></thead><tbody><tr><td>Authorization: Bearer</td><td>String</td><td>We can add in a bearer token in the authorization headers if you require us to.</td></tr></tbody></table>

#### Request body

<table><thead><tr><th width="190.28125">Name</th><th width="149.66015625">Type</th><th>Description</th></tr></thead><tbody><tr><td>match_id<mark style="color:red;">*</mark></td><td>String</td><td><code>match_id</code> generated by you uniquely identifying this match.</td></tr><tr><td>scores<mark style="color:red;">*</mark></td><td>String</td><td>Array of JSON objects, each containing: <a data-footnote-ref href="#user-content-fn-3"><code>rank</code></a>, <a data-footnote-ref href="#user-content-fn-2"><code>sub</code></a>, <a data-footnote-ref href="#user-content-fn-4"><code>score</code></a></td></tr></tbody></table>

#### HTTP response codes

{% tabs %}
{% tab title="200: OK" %}
You must respond with a 200 when you record winners successfully. Here's the response body we expect:

{% code overflow="wrap" %}

```json
{
  "success": true,
  "scores": [
    {
      "rank": 1,
      "sub": "dhruv-123",
      "score": 10,
      "prize": 100,
      "currency_icon": "https://example.com/icon.png"
    },
    {
      "rank": 2,
      "sub": "kamal-123",
      "score": 8,
      "prize": 100,
      "currency_icon": "https://example.com/icon.png"
    },
    {
      "rank": 3,
      "sub": "shivam-123",
      "score": 5,
      "prize": 100,
      "currency_icon": "https://example.com/icon.png"
    }
  ]
}
```

{% endcode %}

At the end of each match, we show a screen where the users of that match can see the final winners. If you have a prize amount that you're crediting the winners with, you can pass that as the `prize` value, along with an icon for your currency in the `currency_icon` value. [**Both of these values**](#user-content-fn-5)[^5] **are optional.** This is what the screen looks like:

![](/files/vclq4kUr5MaTV5Q9o84r)
{% endtab %}
{% endtabs %}

{% hint style="info" %}

* We can also dispatch client-side callbacks for key events related to multiplayer matches. More on it [here](/publishers/gamezop/advanced/multiplayer-games/client-side-callbacks.md).&#x20;
* In addition to us posting match winners' data to you on your endpoint, if you also want to pull data from our system for any specific match, you can use our [Get Match Result API described below](#get-match-result-api).
  {% endhint %}

***

### Gamezop Get Match Result API

This API allows you to pull data from Gamezop's systems for any match played by your users.

#### Gamezop API endpoint

<mark style="color:green;">`GET`</mark> `https://api.gamezop.com/v1/match-result?match_id={your-match-id}`

#### Headers

<table><thead><tr><th width="190.296875">Name</th><th width="150.24609375">Type</th><th>Description</th></tr></thead><tbody><tr><td>Authorization: Bearer<mark style="color:red;">*</mark></td><td>String</td><td>You must ask your Gamezop Account Manager to get your Bearer token created for you. You can then find the Bearer token for this API under <em>Settings &#x26; Admin > API Tokens</em> within the Gamezop Business Dashboard. </td></tr></tbody></table>

#### Query parameters

<table><thead><tr><th width="189.61328125">Name</th><th width="150.01171875">Type</th><th>Description</th></tr></thead><tbody><tr><td>match_id<mark style="color:red;">*</mark></td><td>String</td><td>The <code>match_id</code> that you want match result for. This is the same <code>match_id</code> that you return to us via your <a href="#create-match-api">Create Match API</a>.</td></tr></tbody></table>

#### HTTP response codes

{% tabs %}
{% tab title="200: OK" %}
Expected response body:

```json
{
  "data": {
    "property_id": "1234",
    "game_code": "rJWyhp79RS",
    "room_id": "SNAKE_AND_LADDERS_5e0",
    "match_id": "ab9ce5a2995c5da2047a",
    "scores": [
      {
        "sub": "1257722",
        "is_bot": false,
        "rank": 1,
        "score": 10
      },
      {
        "sub": "3800",
        "is_bot": true,
        "rank": 2,
        "score": 9
      }
    ],
    "match_status": "COMPLETED",
    "match_start_time": "2025-06-11T06:00:00.000Z"
  },
  "success": true,
  "message": ""
}
```

{% endtab %}

{% tab title="401: Unauthorized" %}
Here are the error messages you could receive:

* [*Bearer token is invalid or missing*](#user-content-fn-6)[^6]
  {% endtab %}

{% tab title="400: Bad Request" %}
Here are the error messages you could receive:

* [*match\_id is invalid or missing*](#user-content-fn-7)[^7]
  {% endtab %}
  {% endtabs %}

#### Understanding the response

The table below explains all the fields that we send to you when you receive a 200: OK response from us on the Gamezop Get Match Result API.

<table><thead><tr><th width="250.30859375">Key</th><th>Description</th></tr></thead><tbody><tr><td><code>data.property_id</code></td><td>Your Gamezop Property ID associated with the bearer token that you sent in the ad request</td></tr><tr><td><code>data.game_code</code></td><td>The Gamezop game code on which the match (identified by the <code>match_id</code> you sent in the request query parameters) was played. You can get game codes for all Gamezop games enabled for you via the <a href="/pages/-MdX-XBrMSrHOv6jhI4j">Gamezop All Games API</a>.</td></tr><tr><td><code>data.room_id</code></td><td>The Room ID that you passed to us in the <code>roomDetails</code> object when <a href="/pages/-MdX0-pMR4ktLqUtQ-Sl#generating-game-links-for-multiplayer-games">generating the game link</a>, which eventually led to the creation of the <code>match_id</code> that you are requesting data for.</td></tr><tr><td><code>data.match_id</code></td><td>The <code>match_id</code> that you're requesting data for.</td></tr><tr><td><code>data.scores</code></td><td><p>Array of player score objects. These are all the players that participated in the <code>match_id</code> you are requesting data for, and their scores. Within each object, you receive 4 attributes: <code>sub</code>, <code>is_bot</code>, <code>rank</code> and <code>score</code>.<br></p><ul><li>The <code>sub</code> value here is your user identifier. This is the same as that you pass to us in the <code>roomDetails</code> object when <a href="/pages/-MdX0-pMR4ktLqUtQ-Sl#generating-game-links-for-multiplayer-games">generating the game link</a>. You pass this within the <code>user</code> object within <code>roomDetails</code>.</li><li><code>is_bot</code> is a boolean that helps you identify if that particular player was a bot.</li><li><code>rank</code> identifies that player's rank within the match. The player with rank <code>1</code> is the winner of the match.</li><li><code>score</code> represents that player's latest score within that match.</li></ul></td></tr><tr><td><code>data.match_status</code></td><td>You can receive one of 2 values: <code>COMPLETED</code> or <code>IN_PROGESS</code>. This is also self-explanatory.</td></tr><tr><td><code>data.match_start_time</code></td><td>This is the UTC timestamp representing the time at which the match started.</td></tr><tr><td><code>success</code></td><td>Boolean value that is always <code>true</code>, unless there is an error in the API response</td></tr><tr><td><code>message</code></td><td>String value that is always empty, unless there is an error in the API response</td></tr></tbody></table>

[^1]: If you've charged an entry fee to your users, you can issue a refund in case no match is found.

[^2]: You pass this within the `user` object in the encoded `roomDetails` object.&#x20;

[^3]: Final rank of that user.

[^4]: Gamezop automatically removes the concept of multiple leaderboards from multiplayer matches. The games are modified to only deliver one form of game-play when opened in as multiplayer experiences. Consequently, no `leaderboardId` needs to be passed.

[^5]: `prize` and `currencyIcon`

[^6]: You would receive this if the bearer token sent in the request is invalid, or if it's not sent in the request altogether.

[^7]: You would receive this if the `match_id` query parameter that you sent in the request is invalid, or if it's not sent in the request altogether.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.platform.gamezop.com/publishers/gamezop/advanced/multiplayer-games/receive-winners-data.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.