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

POST https://titleId.playfabapi.com/Client/Matchmake

Request Body

Name Type Description
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 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

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

Responses

Name Type Description
200 OK
400 Bad Request

This is the outer wrapper for all responses with errors

Security

SessionTicket

This API requires a client session ticket, available from any Client Login function.

Type: apiKey
In: header

Definitions

ApiErrorWrapper

The basic wrapper around every failed API response

CollectionFilter

Collection filter to include and/or exclude collections with certain key-value pairs. The filter generates a collection set defined by Includes rules and then remove collections that matches the Excludes rules. A collection is considered matching a rule if the rule describes a subset of the collection.

Container_Dictionary_String_String

A data container

MatchmakeRequest
MatchmakeResult
MatchmakeStatus
Region

ApiErrorWrapper

The basic wrapper around every failed API response

Name Type Description
code
  • integer

Numerical HTTP code

error
  • string

Playfab error code

errorCode
  • integer

Numerical PlayFab error code

errorDetails
  • object

Detailed description of individual issues with the request object

errorMessage
  • string

Description for the PlayFab errorCode

status
  • string

String HTTP code

CollectionFilter

Collection filter to include and/or exclude collections with certain key-value pairs. The filter generates a collection set defined by Includes rules and then remove collections that matches the Excludes rules. A collection is considered matching a rule if the rule describes a subset of the collection.

Name Type Description
Excludes

List of Exclude rules, with any of which if a collection matches, it is excluded by the filter.

Includes

List of Include rules, with any of which if a collection matches, it is included by the filter, unless it is excluded by one of the Exclude rule

Container_Dictionary_String_String

A data container

Name Type Description
Data
  • object

Content of data

MatchmakeRequest

Name Type Description
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 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

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

MatchmakeResult

Name Type Description
Expires
  • string

timestamp for when the server will expire, if applicable

LobbyID
  • string

unique lobby identifier of the server matched

PollWaitTimeMS
  • number

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

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

ServerPublicDNSName
  • string

Public DNS name (if any) of the server

Status

result of match making process

Ticket
  • string

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

MatchmakeStatus

Name Type Description
Complete
  • string
GameNotFound
  • string
NoAvailableSlots
  • string
SessionClosed
  • string
Waiting
  • string

Region

Name Type Description
Australia
  • string
Brazil
  • string
EUWest
  • string
Japan
  • string
Singapore
  • string
USCentral
  • string
USEast
  • string

Error Codes

Name Code
BuildNotFound 1032
GameModeNotFound 1025