Developer Console
Sign In
Sign In
Developer Console

Manage Teams with API

Use the Admin API to create and manage team competitions.

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

Admin API tasks

  1. Create prizes for the tournament.

    Use the existing Add Prize List API method.

  2. Create a team tournament.

    Use the existing Add Tournament API method and set the new fields to specify a team tournament.

  3. Create teams to compete in the tournament.

    Use the new Create Team API method.

  4. Add players to these teams.

    Use the new Add Players to Team API method.

    Admin API for Teams

    Leaderboards and Tournaments Admin API provides the following methods to create and manage teams and team-based tournaments.

    Create prizes

    Call the Create Prize List method to create prizes. This method is identical for single-player and team tournaments.

    When you set up prizes for team tournaments, ensure that you select prizes that multiple people can claim. Do not use single-use prizes for team tournaments, because each player on the team will be awarded the same prize.

    Example request body

    {
"prizes": [
        {
            "title": "1000 Crystals",
            "prizeInfo": "1000_CRYSTAL_PACK",
            "description": "To be used on any in-game purchase."
        },
        {
            "title": "10 Crystals",
            "prizeInfo": "10_CRYSTAL_PACK",
            "description": "To be used on any in-game purchase."
        }
    ]
}

    For exact syntax and parameters, see Create Prize List in the Admin API reference.

    Create a team tournament

    To create a team tournament, call Add Tournament. Set the participantType parameter to TEAM.

    You can specify a minimum and maximum team size that can enter the tournament. For example, to create a 5-versus-5 tournament, set min and max to 5. Players can enter the tournament if the team they represent has five or fewer actual players and a team maximum size of five.

    Example request body

    {
    "participantType": "TEAM",
    "dateStart": "1514793600000",
    "dateEnd":  "1514966400000",
    "title": "5v5 Brawl",
    "prizeBundles": [
        {
            "title": "First Place",
            "description": "Win 1000 Crystals",
            "rankFrom": 1,
            "rankTo": 1,
            "prizeIds": ["2a9f8d34-d856-4314-84ad-c5c86836ecbc"]
        },
        {
            "title": "Second Place",
            "description": "Win 10 Crystals",
            "rankFrom": 2,
            "rankTo": 2,
            "prizeIds": ["7887c4e7-9922-4712-b05e-495d0fbaa798"]
        }
    ],
    "teamSizeMin": 5,
    "teamSizeMax": 5
}

    For exact syntax and parameters, see Add Tournament in the Admin API reference.

    Create a team

    Call the Create Team method to create a team.

    You must specify the maximum team size. Add Tournament uses this number to decide if a team can join a competition that has a minimum and maximum team size requirement. There is essentially no upper limit on team size, as the range of values for teamSizeMax is 1 to 1,000,000,000.

    Example request body

    {
    "teamName": "The First Responders",
	"teamSizeMax": 5
}

    For exact syntax and parameters, see Create Team in the Admin API reference.

    Add players to a team

    Call the Add Players to Team method to add players to a team.

    You need to provide a list of externalPlayerIds in the request body. The response returns the remaining size of the team.

    Example request body

    {
	"externalPlayerIds": ["9496b5dd-432e-4bef-8297-b6f7b9e1fe29", "b1f2af5b-8bba-480a-831f-0a5f1af94f1c"]
}

    Notes

    • You can add the same players to multiple teams.
    • If a teams contains their maximum number of players, further add-player requests are rejected.
    • If you try to add a player that is already on the team, the request is ignored.

    For exact syntax and parameters, see Add Players to Team in the Admin API reference.

    Remove players from a team

    To remove players from a team, call the Remove Players from Team method.

    In the request body, you must provide the list of externalPlayerIds to be deleted. The method response returns the remaining size of the team.

    Example request body

    {
	"externalPlayerIds":
        ["9496b5dd-432e-4bef-8297-b6f7b9e1fe29",
            "b1f2af5b-8bba-480a-831f-0a5f1af94f1c"]
}
}

    Notes

    • Any tournament that is completed before the player is removed will not be affected.
    • When you remove a player from a team, if that team is participating in a tournament that is not completed yet, the player's contribution to the team score is removed.
    • If a player is removed from a team during a team tournament (where that player was representing their team), the player will not receive any prizes that the team is awarded.

    For exact syntax and parameters, see Remove Players from Team in the Admin API reference.