API Methods for Team Tournaments
The Leaderboards and Tournaments API provides methods to create and manage team competitions. Use the task flows described below as a guide for planning the updates that you will need in your game to support team tournaments.
Task Flows for a Team Tournament
The following steps describe the overall flow for creating and managing a Team Tournament. The comments for each step indicate differences in the API compared with creating an individual tournament. For the game API, the comments also indicate user interfaces in the game that you may need to add or modify to support team tournaments.
Game API tasks
-
Players discover the team tournaments.
Use the existing Get Tournaments API method and set the filters to discover team tournaments. You may need additional game UI to display team tournaments.
-
Players enter the tournament and indicate the team that they want to represent.
Use the existing Enter Tournament API method with
teamIdin the request body. If your game supports players being members of more than one team, you need to add game UI for the players need to select their team when they enter the tournament. -
Players submit their score.
Use the existing Submit Score API method and set the additional parameters for team tournaments.
-
Players view the leaderboard to see the team score.
Use the existing Get Leaderboard API method that now supports teams. You may need to add game UI to display a team leaderboard.
-
Player views match details and gets their awarded prize Id.
Use the existing Get Match Details API method, which returns additional fields for a team tournament. You may need to modify game UI to indicate a team tournament.
-
Player claims their awarded prize.
Use the existing Claim Prizes API method.
Game API for Teams
To support team tournaments, the game needs to support the following API integration points and add the appropriate game UI as required:
- Get team details
- Player enters a team tournament
- Team leaderboards
- Players receive prizes when the team wins
Get team details
To get details about a team, including the team members, call the Get Team Details method.
Specify the team ID in the request. The response includes the following information:
- the team name
- maximum size of the team
- whether this player is a member of this team
- player Ids of the other players in the team.
Example response body
{
"teamId": "e5ab6709-9520-470a-baca-0480a0c9fc48",
"teamName": "The First Responders",
"teamSizeMax": 5,
"isPlayerInTeam": true,
"externalPlayerIds": [
"2b5c0474-8f29-43e8-a184-84bd14738e25",
"e3716a15-ffcf-45c5-bf92-d9a0c59abe05"
]
}
For exact syntax and parameters, see Get Team Details in the Game API reference.
Player enters a team tournament
For the player to enter a team tournament for the first time, call the Enter Team Tournament method. This finds an available match in the tournament, based on the maximum number of matches per tournament and min/max team size per match.
In a team tournament, the player specifies the team that they represent when they enter the tournament. The significance to the player is that prize allocation is based on the team score (not their individual score). Players submit their scores as they would for an individual tournament, but the scores contribute to a collective team score. The team score determines whether the team wins any prizes. If a team wins a prize, each contributing player in the team can claim the prize.
You must provide the Team ID parameter in the body of the request.
{
"teamId": "de4ae20c-829d-476c-b3a1-d29532086e60"
}
For exact syntax and parameters, see Enter Team Tournament in the Game API reference.
Team leaderboards
Call Get Team leaderboards to get the team leaderboard for the match that you specify in the request.
This method applies to individual and team tournaments. The information in the response depends on the tournament type (you specified tournament type when you created the tournament). For a team tournament, the method returns a team leaderboard.
{
"leaderboard": [
{
"teamId": "5ff9cd4a-435a-483e-8152-9a55c32199f7",
"teamName": "team278",
"score": 70,
"hasPlayerContributed": true,
"rank": 1
},
{
"teamId": "1a91fe23-a39c-412e-bec2-43f7a3cd1fed",
"teamName": "team5846",
"score": 50,
"rank": 2
}
],
"next": "/matches/f106bf39-<truncated>zM4ZTY="
}
For exact syntax and parameters, see Get Team leaderboards in the Game API reference.
Team wins prizes
If a team wins a prize, each player in the team will be awarded the same prize. When they claim their prize, prizeInfo will be the same for each player.
To display the prizes that a player may claim, call the getMatches method, filtered by unclaimed-prizes.
When the player selects one or more prizes, call Claim Prizes to get the claim URLs of the prizes.