This article gives a thorough description of the matchmaking API.

If you have any questions, contact support at support@polynect.io.

Authentication

To use the API, a bearer token has to be included in the request. The token can be found by going to the Account tab in the app.




This token should only be used from your backend and not be available in game clients.

Start matchmaking

To start matchmaking, make a POST request with the game's ID and other match data described below. The data needed depends on the matchmaking configuration.


POST http://api.polynect.io/v1/matches/match

NameRequiredDescriptionType
gameyesThe ID of the game to match forstring
optionsno*Key value pairs if needed by the game's matchmaking configuration.object
playerno*Player specific data used for matching with other players.object
player.idnoA unique ID for the player. One will be generated if omitted.string
characterno*Character data used for matching in games in which a player may play as one of many characters.object
* Required only if used in the game's matchmaking configuration

Start matchmaking as a group

A group of players can look for other players together and end up in the same match with a group request. The API is similar to finding a match for a single players, except that the player data are elements in an array.


POST http://api.polynect.io/v1/matches/match

NameRequiredDescriptionType
gameyesThe ID of the game to match forstring
groupyesAn array containing matchmaking data for each player.object[]
group.*.optionsno*Key value pairs if needed by the game's matchmaking configuration.object
group.*.playerno*Player specific data used for matching with other players.object
group.*.player.idnoA unique ID for the player. One will be generated if omitted.string
group.*.characterno*Character data used for matching in games in which a player may play as one of many characters.object
* Required only if used in the game's matchmaking configuration

List matches

List all existing matches with the following request. This includes matches belonging to all your games, use query parameters to filter the result.


GET http://api.polynect.io/v1/matches

Query parameters

Most fields can be included in a query, including `attributes` which are defined by your matchmaking configuration and `data` fields which can be set via the API. To query on a boolean field, use the string "true" or "false" as the value.

?size=&min=&max=&game.id=&status=&attributes.<key>=&data.<key>=&open=

Pagination

For pagination, use the query parameters skip and limit. The default values are 0 and 10 respectively. To change page, limit should be held constant and skip should then be incremented by the selected limit.


Response
NameDescriptionType
idA unique ID for the match.string
sizethe number of players currently in the match.number
minThe minimum number of players needed to start the game.number
maxThe maximum number of players that can be in the match at once.number
game.idThe ID of the match's gamestring
statusIndicates in which state the match is in.enum{waiting, ready}
attributesKey value pairs used for matching with other players.object
dataKey value pairs set by you as a developer via.object
openTrue if other players may join the match given that size < maxboolean
playersA list of players that are in the match.object[]
charactersA list of characters in the match. One for each player.object[]
If the result is returned to the game client, make sure to not include fields in the `data` field that should only be available to players in the match such as a secret token to a game server.

Add a player to an existing match

A player can manually be added to an existing match. This may be useful to let the player select a match from a list of matches or to implement invitations, in which case the player is added to the match after accepting the invitation.


POST http://api.polynect.io/v1/matches/{match_id}/players

The request parameters are the same as when requesting automatic matchmaking.


NameRequiredDescriptionType
gameyesThe ID of the game to match forstring
optionsno*Key value pairs if needed by the game's matchmaking configuration.object
playerno*Player specific data used for matching with other players.object
player.idnoA unique ID for the player. One will be generated if omitted.string
characterno*Character data used for matching in games in which a player may play as one of many characters.object
* Required only if used in the game's matchmaking configuration

Remove a player from a match

If a player chooses to leave or has been disconnected for a certain amount of time, it is often necessary to remove it from the match so that another player can join. This is done with a delete request with the match and player IDs.


DELETE http://api.polynect.io/v1/matches/{match_id}/players/{player_id}

Edit a match

Editing a match is useful to set custom data on the match or open/close to allow/deny new players from joining the match.


PUT http://api.polynect.io/v1/matches/{match_id}

Only a few of the properties of the match can be modified. The request works like a patch so only the properties you want to change need to be included in the request.


NameRequiredDescriptionType
datanoKey value pairs set by you as a developer via.object
opennoTrue if other players may join the match given that size < maxboolean

Delete a match

After a game has ended and all the players have left, you may want to delete the match, although this is not necessary. This can however be done with a delete request.


DELETE http://api.polynect.io/v1/matches/{match_id}

Got an idea for a game?


We would love to hear about it and to discuss how to best integrate it with Polynect. Other business inquiries are also welcome. Please write to adam@polynect.io

Copyright © Polynect