Match Configuration

The Match Configuration is sent to the Game Server which is responsible for dispatching the match configuration to all Game Clients to allow the respective players to join the match. The configuration is sent to the Game Server endpoint provided by the Game Developer and it is compliant to the specifications provided in the Game Studio > Main Configuration > Match Lifecycle section, under the Match Configuration > Request Body Template panel.

The request payload is essentially a standard JSON object, common to all games, containing information such as faction composition, afk timeout, spectators; it also contains some game-specific data, defined by the chosen game mode, in the game_custom_data property.

The payload can be transformed, just before it is sent to the Game, to fit the expected shape on the Game Server side using a custom ECMAScript specified in the Request Transformation panel.

Request Transformation example

function addField(h) {
  h.body.someProperty = "someValue";
  return h;
}
addField(scriptHelper);

Endpoint Specifications

Payload overview

The JSON schema of the match configuration payload can be found here.

A sample payload for a 2-factions matchmaking match is the following:

{
  "match_id": "12345-2-1",
  "faceit_match_id": "12345",
  "game": "tic-tac-toe",
  "region": "EU",
  "round": 1,
  "competition": {
    "id": "abcd-efgh",
    "type": "matchmaking"
  },
  "factions": {
    "faction1": {
      "id": "aaaa-bbbb",
      "leader": "1111-2222",
      "name": "team_foo",
      "avatar": "https://distribution.faceit.com/images/something.jpeg",
      "players": [
        {
          "id": "aaaa-bbbb",
          "nickname": "foo",
          "game_id": "1111-2222",
          "game_name": "TheFoo",
          "anticheat_required": false
        }
      ],
      "coaches": null
    },
    "faction2": {
      "id": "cccc-dddd",
      "leader": "3333-4444",
      "name": "team_bar",
      "avatar": null,
      "players": [
        {
          "id": "cccc-dddd",
          "nickname": "bar",
          "game_id": "3333-4444",
          "game_name": "OGbar",
          "anticheat_required": false
        }
      ],
      "coaches": [
        {
          "id": "eeee-ffff",
          "nickname": "baz",
          "game_id": "5555-6666",
          "game_name": "baz",
          "anticheat_required": false
        }
      ]
    }
  },
  "game_custom_data": {},
  "type": "DEFAULT",
  "allow_ongoing_join": false,
  "series_id": null,
  "roster_with_substitutes": false,
  "version": 2
}

Field Descriptions

Request Payload

Field	Type	Description
match_id	String	The FACEIT unique identifier of the match instance. It will be different for every "BestOf" round or potential reconfigurations.
faceit_match_id	String	The identifier the players will see on FACEIT platform.
game	String	The identifier of the game title.
region	String	The identifier of the game region where the match was created.
round	Integer	The round counter in case of "BestOf" matched. Always greater than 0.
competition	Competition	The information about the competition which generated the match. See Competition section.
factions	map<String,Faction>	The factions that compose the match. Each faction is defined using factionN string key. See Faction section for details about the faction object.
game_custom_data	Object	Game-specific settings defined by the Game Mode.
type	String	The match type. It can be DEFAULT or COMMUNITY_SERVER.
allow_ongoing_join	Boolean	The flag that drives the abity to join ongoing matches using special commands. If set to true the game should accept player add/remove commands (for advanced integrations).
series_id	String	The identifier of a match series, in case of Community Server matches. Optional value, null if not defined.
roster_with_substitutes	Boolean	The flag that tells if the faction rosters contain also substitutes along with players.
version	Integer	The payload version, in case of future changes. Statically set to 2

Competition

Field	Type	Description
id	String	The FACEIT identifier of the competition.
type	String	The type of competition. Can be matchmaking, hub, championship, community_server

Faction

Field	Type	Description
id	String	The FACEIT identifier of the faction.
leader	String	The in-game player identifier of the captain of the faction.
name	String	The FACEIT name of the faction.
avatar	String	The url of the avatar image of the faction. Optional value, null if not defined.
players	array<Player>	The roster of the faction. See Player section for details about the player object.
coaches	array<Player>	The list of coaches of the faction. See Player section for details about the player object. Optional value, null if not defined.

Player

Field	Type	Description
id	String	The FACEIT identifier of the player.
nickname	String	The FACEIT nickname of the player.
game_id	String	The in-game player identifier.
game_name	String	The in-game player nickname.
anticheat_required	Boolean	The flag that tells if the players should have the anti-cheat client running in order to play the match. Only for integrations with AntiCheat.

Response Codes and Errors

HTTP Codes	Description
2xx	Match configuration call will be considered successful.
4xx	Match configuration call will be considered failed.
5xx	Match configuration call will be considered failed.