This tutorial will get you up and running with Polynect Matchmaking. First, we will cover how to set up a game with a matchmaking configuration and then we will use the API to create matches.

Create an account

To start configuring your game, you need to sign up for a free account if you haven't already. After signing up, you'll receive an email with a link to complete the registration. Click the button below to get going.

Create a free account

Configure a game

As you'll notice after you sign up, you get to select a name for your first game. The name is just for you and you can change it whenever you want.

To start, the game is configured for 2 players and can be changed by selecting different values for minimum and maximum. For many games, using the same value for minimum and maximum makes most sense. The other options are attributes and roles which we will get back to in a minute. Right now, the configuration is ready to be used in a game as well as for our testing.

Start matchmaking

A POST request should be sent to to initiate matchmaking.

These are the post parameters for the request.

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

Replace the token and game_id with your values. The game's id can be found by going to the game's General page. The token can be found by going to Manage Account in the top right drop-down menu.

Authorization: Bearer <developer_token>
    "game": <game_id>
    "player": {}

By making the request above, you should see response data similar to the data below. For a description of the fields, there is a table underneath.

    "id": "57bb204d5b95c2030031a5dd",
    "size": 1,
    "min": 2,
    "max": 2,
    "game": {
        "id": "57ba06b51815a90300929309"
    "status": "waiting",
    "attributes": {},
    "open": true,
    "players": [{
        "id": "57bb204d5b95c2030031a5da"
    "characters": [{
        "player": {
            "id": "57bb204d5b95c2030031a5da"

Match response

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
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 you run it again, the same match should be found and the status should now be set to ready.

As you may have noticed, player ids were created for us. This works when testing, but for your implementation, you should provide it as a unique identifier for each player. It is preferably stored in your game's backend or created when starting a new session. Also, it allows players to be in multiple matches at once or to start looking for a different match before leaving the current one, without risking to be matched with itself.

{"game": "", "player": {"id": "<insert-id-here>"}}

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

Copyright © Polynect