Receive data on match winners

Gamezop can post data on winners of multiplayer games on your webhook. This document details out how.

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

• 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 (webhook created by you where we push data)

• 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

POST 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

Name	Type	Description
Authorization: Bearer	String	We can add in a bearer token in the authorization headers if you require us to.

Request body

Name	Type	Description
room_id*	String	roomId passed by you in the encoded roomDetails object
status*	String	One of 2 options will be passed: MATCH_FOUND or
players*	String	Array of matched together.

HTTP response codes

200: OK

You must respond with a 200 when you return a match_id

Expected response body:

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

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.

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.

---

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

POST 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

Name	Type	Description
Authorization: Bearer	String	We can add in a bearer token in the authorization headers if you require us to.

Request body

Name	Type	Description
match_id*	String	match_id generated by you uniquely identifying this match.
scores*	String	Array of JSON objects, each containing: , ,

HTTP response codes

200: OK

You must respond with a 200 when you record winners successfully. Here's the response body we expect:

{
  "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"
    }
  ]
}

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. are optional. This is what the screen looks like:

• We can also dispatch client-side callbacks for key events related to multiplayer matches. More on it here.

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

---

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

GET https://api.gamezop.com/v1/match-result?match_id={your-match-id}

Headers

Name	Type	Description
Authorization: Bearer*	String	You can find the Bearer token for the Gamezop Get Match Result API in the Settings section of the Gamezop Business Dashboard. You can also ask your Gamezop Account Manager to share it with you.

Query parameters

Name	Type	Description
match_id*	String	The match_id that you want match result for. This is the same match_id that you return to us via your Create Match API.

HTTP response codes

200: OK

Expected response body:

{
  "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": ""
}

401: Unauthorized

Here are the error messages you could receive:

• "Bearer token is invalid or missing.": Self-explanatory. You would receive this if the bearer token sent in the request is invalid, or if it's not sent in the request altogether.

400: Bad Request

Here are the error messages you could receive:

• "match_id is invalid or missing.": Self-explanatory. 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.

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.

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