Documentation

Matchmake

Attempts to locate a game session matching the given parameters. If the goal is to match the player into a specific active session, only the LobbyId is required. Otherwise, the BuildVersion, GameMode, and Region are all required parameters. Note that parameters specified in the search are required (they are not weighting factors). If a slot is found in a server instance matching the parameters, the slot will be assigned to that player, removing it from the availabe set. In that case, the information on the game session will be returned, otherwise the Status returned will be GameNotFound.

Request Details

MatchmakeRequest
Request Properties
BuildVersion String

Build version to match against. [Note: Required if LobbyId is not specified]

CharacterId String

Character to use for stats based matching. Leave null to use account stats.

GameMode String

Game mode to match make against. [Note: Required if LobbyId is not specified]

LobbyId String

Lobby identifier to match make against. This is used to select a specific Game Server Instance.

Region Region

Region to match make against. [Note: Required if LobbyId is not specified]

StartNewIfNoneFound Boolean

Start a game session if one with an open slot is not found. Defaults to true.

StatisticName String

Player statistic to use in finding a match. May be null for no stat-based matching.

TagFilter CollectionFilter

Filter to include and/or exclude Game Server Instances associated with certain Tags

POST https://{{TitleID}}.playfabapi.com/Client/Matchmake
    Content-Type: application/json
    X-Authentication: <user_session_ticket_value>
{
  "BuildVersion": "5.01",
  "Region": "USCentral",
  "GameMode": "0",
  "TagFilter": {
    "Includes": [
      {
        "Data": {
          "level_cap": "0"
        }
      }
    ],
    "Excludes": [
      {
        "Data": {
          "newbie": "0"
        }
      }
    ]
  }
}
        

Response Details

MatchmakeResult
Result Properties
Expires String

timestamp for when the server will expire, if applicable

LobbyID String

unique lobby identifier of the server matched

PollWaitTimeMS int32

time in milliseconds the application is configured to wait on matchmaking results

ServerIPV4Address String

IPV4 address of the server

ServerIPV6Address String

IPV6 address of the server

ServerPort int32

port number to use for non-http communications with the server

ServerPublicDNSName String

Public DNS name (if any) of the server

Status MatchmakeStatus

result of match making process

Ticket String

server authorization ticket (used by RedeemMatchmakerTicket to validate user insertion into the game)

Sample Response

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
{
  "code": 200,
  "status": "OK",
  "data": {
    "LobbyID": "4006214",
    "ServerHostname": "192.168.0.1",
    "ServerIPV6Address": "2600:1f18:70d:5100:8949:a309:976a:e6fa",
    "ServerPort": 9000,
    "Ticket": "e98yf289f248902f4904f0924f9pj",
    "Status": "Waiting"
  }
}

Authentication

SessionTicket

Possible Error Codes

Name Code
BuildNotFound 1032
GameModeNotFound 1025