Admin API Reference

Overview

This API enables administrative actions for developers to manage their Amazon Leaderboards and Tournaments competitions. The API is accessed using an admin api key. The admin API is intended to run from an admin machine; it is not integrated into the game, like the game API.

Note: As our APIs grow and develop, we will continue to add functionality and attributes to our request/response models. To ensure backwards compatibility, we will not remove or change existing attributes. To help prevent breaking your implementation, we encourage that you don't strictly validate schemas and ignore unknown properties.

Method	Type	Path	Description
Update Game	PUT	/games/{gameId}	Update the game to enable stats-based tournaments.
Register Player	POST	/players/register	Register & create a new player token with an identifier that enables players to play across multiple devices.
Add Prize List	POST	/prizes	Add a list of in-app prizes for use in tournaments.
Get Prize List	GET	/prizes	Get a list of prizes for use in tournaments.
Delete Prize	DELETE	/prizes/{prizeId}	Delete an in-app prize.
Add Requirement List	POST	/requirements	Add a list of requirements for use against tournaments.
Get Requirement List	GET	/requirements	Get a list of requirements for use against tournaments.
Create Team	POST	/teams	Create a team for players to join and compete in tournaments with.
Add Players to Team	PUT	/teams/{teamId}/players	Add a list of players to a specified team.
Remove Players from Team	DELETE	/teams/{teamId}/players	Remove a list of players from a specified team.
Add Tournament	POST	/tournaments	Add a tournament for entities like players to join and compete against one another.
Add Tournament Series	POST	/tournaments/series	Creates a series of recurring tournaments.
Close Tournament	POST	/tournaments/{tournamentId}/close	Manually close a tournament early, determining winners and prizes.
Delete Upcoming Tournament	DELETE	/tournaments/{tournamentId}	Deletes a tournament that has not started yet.

Version information

Version : v1

License information

The API and these materials are Program Materials subject to our Program Materials License Agreement.

URI scheme

Host : admin-api.amazongameon.com
Base Path : /v1
Schemes : HTTPS

Paths

Update Game

PUT /games/{gameId}

Description

Update the game to enable stats-based tournaments. Please note that deleting stats is not supported at this time. For subsequent calls to add stats, existing stats are required to be present in the body.

Parameters

Type	Name	Description	Schema
Header	Content-Type required	`application/json`	string
Header	X-Api-Key required	Admin API key. This is provided when you register your game.	string
Path	GameId required	Game Id. This is provided as GameId when you register your game.	string
Body	updateGameRequest required	Information required to update game settings.	UpdateGameRequest

Responses

HTTP Code	Description	Schema
204	Successfully updated the game.	No Content
400	Invalid request parameters such as missing previously declared stats or having duplicate stats.	No Content
403	Forbidden. Invalid API Key or Game Id	No Content

Consumes

application/json

Produces

application/json

Example HTTP request

POST /games/7dd9d75b-8786-4b44-b1fe-a8cd50f0f7e5
Content-Type: application/json
X-Api-Key: d2d0b961-a5ce-45c7-9dbe-a63061ee229c
{  
   "gameStats":[  
      "kills", "assists", "gold"
   ]
}

Example HTTP response

Response 204

Add Prize List

POST /prizes

Description

Add a list of in-app prizes for use in tournaments.

Parameters

Type	Name	Description	Schema
Header	Content-Type required	`application/json`	string
Header	X-Api-Key required	Admin API key. This is provided when you register your game.	string
Body	addPrizeListRequest required	Information required to add a list of in-app prizes.	AddPrizeListRequest

Responses

HTTP Code	Description	Schema
200	Successfully added at least one prize.	AddPrizeListResponse
400	Invalid request parameters.	No Content
401	Unauthorized.	No Content
403	Forbidden. Invalid API Key.	No Content

Consumes

application/json

Produces

application/json

Example HTTP request

Request

POST /prizes
Content-Type: application/json
X-Api-Key: d2d0b961-a5ce-45c7-9dbe-a63061ee229c

Request body

{
  "prizes": [
    {
      "description": "This chest contains better loot than the Silver Chest.",
      "imageUrl": "https://s3.amazonaws.com/tournament-prizes/Prize-Item-1.png",
      "title": "Golden Chest",
      "prizeInfo": "GOLDEN_CHEST_0124"
    },
    {
      "description": "Live forever with this bundle of health potions.",
      "imageUrl": "https://s3.amazonaws.com/tournament-prizes/Prize-Item-1.png",
      "title": "100 Health Potions",
      "prizeInfo": "HEALTH_POTIONS_100"
    }
  ]
}

Example HTTP response

Response 200

{
  "addedPrizes": [
    {
      "description": "This chest contains better loot than the Silver Chest.",
      "imageUrl": "https://s3.amazonaws.com/tournament-prizes/Prize-Item-1.png",
      "prizeId": "caf9a785-d6e8-4990-bf63-49f7d485a8d9",
      "title": "Golden Chest",
      "prizeInfoType": "VENDOR"
      "prizeInfo": "GOLDEN_CHEST_0124"
    },
    {
      "description": "Live forever with this bundle of health potions.",
      "imageUrl": "https://s3.amazonaws.com/tournament-prizes/Prize-Item-1.png",
      "prizeId": "65d738d1-7e81-450e-97c0-79352284145a",
      "title": "100 Health Potions",
      "prizeInfoType": "VENDOR",
      "prizeInfo": "HEALTH_POTIONS_100"
    }
  ]
}

Add Requirement List

POST /requirements

Description

Add a list of requirements for use against tournaments.

Parameters

Type	Name	Description	Schema
Header	Content-Type required	`application/json`	string
Header	X-Api-Key required	Admin API key. This is provided when you register your game.	string
Body	requirements required	List of requirements to add to Amazon Leaderboards and Tournaments.	AddRequirementListRequest

Responses

HTTP Code	Description	Schema
200	Successfully added at least one requirement.	AddRequirementListResponse
400	Invalid request parameters.	No Content
401	Unauthorized.	No Content
403	Forbidden. Invalid API Key.	No Content

Consumes

application/json

Produces

application/json

Example HTTP request

Request

POST /prizes
Content-Type: application/json
X-Api-Key: d2d0b961-a5ce-45c7-9dbe-a63061ee229c

Request body

{
  "requirements": [
    {
      "name": "Player is VIP",
      "description": "The player has VIP status.",
      "type": "value",
      "key": "status",
      "value": "VIP"
    },
    {
      "name": "Player is a beginner",
      "description": "The player has a skill between 0 and 10.",
      "type": "range",
      "key": "League",
      "high": 10,
      "low": 0
    },
    {
      "name": "Greater Seattle Area",
      "description": "The GPS coordinates of the player is located in the Greater Seattle Area",
      "type": "gps",
      "key": "gpsCoordinates",
      "permittedAreas": [
        {
          "gpsCoordinates": {
            "latitude": 47.60604,
            "longitude": -122.3328
          },
          "radius": 10,
          "radiusUnits": "KILOMETERS"
        }
      ]
    }
  ]
}

Example HTTP response

Response 200

{
  "addedRequirements": [
    {
      "name": "Player is VIP",
      "description": "The player has VIP status.",
      "type": "value",
      "key": "status",
      "value": "VIP",
      "requirementId": "f17abf7f-df0a-4b78-b28a-ddad30f9abf7"
    },
    {
      "name": "Player is a beginner",
      "description": "The player has a skill between 0 and 10.",
      "type": "range",
      "key": "League",
      "high": 10,
      "low": 0,
      "requirementId": "d00d6524-9aaf-4c57-aee3-ec5fe07946ce"
    },
    {
      "name": "Greater Seattle Area",
      "description": "The GPS coordinates of the player is located in the Greater Seattle Area",
      "type": "gps",
      "key": "gpsCoordinates",
      "permittedAreas": [
        {
          "gpsCoordinates": {
            "latitude": 47.60604,
            "longitude": -122.3328
          },
          "radius": 10,
          "radiusUnits": "KILOMETERS"
        }
      ],
      "requirementId": "7ccbfba8-61b8-4abe-a8f1-59d54e324312",
    }
  ]
}

Create Team

POST /teams

Description

Create a team for players to join and compete in tournaments with.

When creating a team you must specify a maximum number of players that are able to join the team. This number will be used to gate access to team competitions that specify a minimum and/or maximum team size requirement – see Add Tournament for more information.

Parameters

Type	Name	Description	Schema
Header	Content-Type required	`application/json`	string
Header	X-Api-Key required	Admin API key. This is provided when you register your game.	string
Body	createTeamRequest required	Request containing information to create a team.	CreateTeamRequest

Responses

HTTP Code	Description	Schema
200	Team created successfully.	CreateTeamResponse
400	Invalid request parameters.	No Content
403	Forbidden. Invalid API Key.	No Content

Consumes

application/json

Produces

application/json

Example HTTP request

Request

POST /teams
Content-Type: application/json
X-Api-Key: d2d0b961-a5ce-45c7-9dbe-a63061ee229c

Request body

{
  "teamName": "Team Name",
  "imageUrl": "https://amazon.com/image.png",
  "teamSizeMax": 5
}

Example HTTP response

Response 200

{
  "teamId": "f9b12bf7-a50e-4cea-b320-e0814cf47616",
  "teamName": "Team Name",
  "imageUrl": "https://amazon.com/image.png",
  "teamSizeMax": 5
}

Add Players to Team

PUT /teams/{teamId}/players

Description

Add a list of players to a specified team.

Teams have a maximum size when created; additional players cannot be added once the maximum size is met. If a player is re-added, they will not consume additional space within the team and will be treated as a no-op.

Parameters

Type	Name	Description	Schema
Header	Content-Type required	`application/json`	string
Header	X-Api-Key required	Admin API key. This is provided when you register your game.	string
Path	teamId required	The ID of the team that players should be added to.	string
Body	teamPlayerListRequest required	A list of player IDs to add to the specified team.	TeamPlayerListRequest

Responses

HTTP Code	Description	Schema
200	All players successfully added to the team.	AddTeamPlayerListResponse
400	Invalid request parameters.	No Content
403	Forbidden. Invalid API Key.	No Content
404	The specified Team ID was not found.	No Content
409	Unable to add all players due to space constraints.	No Content

Consumes

application/json

Produces

application/json

Example HTTP request

Request

PUT /teams/f9b12bf7-a50e-4cea-b320-e0814cf47616/players
Content-Type: application/json
X-Api-Key: d2d0b961-a5ce-45c7-9dbe-a63061ee229c

Request body

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

Example HTTP response

Response 200

{
  "teamSpotsRemaining": 3
}

Remove Players from Team

DELETE /teams/{teamId}/players

Description

Remove a list of players from a specified team.

When a player is removed from a team, they are also removed from any tournaments where they are representing said team if the tournament is in state OPEN or CLOSED where. Upon removal, the team's score will also be deducted/adjusted to reflect the player removal. The player will no longer be eligible for any prizes that may be awarded upon the tournament closing. Tournaments that are completed (tournamentState is COMPLETED) before the player is removed will not be affected. See ()[] for more information on tournament state.

A player cannot be removed if one or more tournaments they are participating are in state WAITING_TO_BE_CLOSED or WAITING_TO_BE_COMPLETED and will result in a partial success. In these cases we encourage you to try to remove the players in a subsequent call.

Parameters

Type	Name	Description	Schema
Header	Content-Type required	`application/json`	string
Header	X-Api-Key required	Admin API key. This is provided when you register your game.	string
Path	teamId required	The ID of the team that players should be added to.	string
Body	teamPlayerListRequest required	A list of player IDs to remove from the specified team.	TeamPlayerListRequest

Responses

HTTP Code	Description	Schema
200	All players successfully removed from the team.	RemoveTeamPlayerListResponse
207	At least one player unable to be removed from the team.	RemoveTeamPlayerListResponse
400	Invalid request parameters.	No Content
403	Forbidden. Invalid API Key.	No Content
404	The specified Team ID was not found.	No Content
409	All players specified are not apart of the team and therefore cannot be removed.	No Content

Consumes

application/json

Produces

application/json

Example HTTP request

Request

DELETE /teams/f9b12bf7-a50e-4cea-b320-e0814cf47616/players
Content-Type: application/json
X-Api-Key: d2d0b961-a5ce-45c7-9dbe-a63061ee229c

Request body

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

Example HTTP response

Response 200

{
  "teamSpotsRemaining": 5
}

Add Tournament

POST /tournaments

Description

Add a tournament for entities like players to join and compete against one another. A tournament created with this endpoint currently has two different participant types: individual and team.

Individual Tournament

In an individual tournament, players will enter and submit score to compete on an individual bases for a chance to win. When calling the leaderboard for this tournament will display a list of players and their current ranks as they relate to one-another.

Team Tournament

In a team tournament, players will enter (specifying the team they represent) and submit score which contributes to a collective team score for a chance for the entire team to win. If a team wins prize(s), each individual player within the team, at the time the tournament closes, will be provided a copy of that prize that can be claimed. For this reason, please ensure that the prizeInfo for each prize provided can be claimed by multiple players – see AddPrizeListRequest_Prize for more information.

Parameters

Type	Name	Description	Schema
Header	Content-Type required	`application/json`	string
Header	X-Api-Key required	Admin API key. This is provided when you register your game.	string
Body	addTournamentRequest required	Information required to add either an individual or team tournament.	AddIndividualTournamentRequest AddTeamTournamentRequest

Responses

HTTP Code	Description	Error Codes	Schema
200	Successfully added the tournament.	None	AddTournamentResponse
400	Invalid request parameters.	[3]	No Content
403	Invalid x-api-key. Provide a valid Admin API Key in the x-api-key header.	[1]	No Content

See Error Codes for error code details.

Consumes

application/json

Produces

application/json

Example HTTP request (with participantType `INDIVIDUAL`)

Request

POST /tournaments
Content-Type: application/json
X-Api-Key: d2d0b961-a5ce-45c7-9dbe-a63061ee229c

Request body

{
  "countryCodes": [
    "US", "CA"
  ],
  "dateEnd": 1515119589135,
  "dateStart": 1515105189135,
  "description": "Tournament description",
  "entryRequirements": [
    ["99208d38-cac9-45fe-8bfd-954ff7e3ae11"],
    ["35831019-b1d7-461a-9af9-22aa4abff68f", "8e37e627-25de-42cf-83df-4bae958d33de"]
  ],
  "visibilityRequirements": [
    ["99208d38-cac9-45fe-8bfd-954ff7e3ae11"],
    ["35831019-b1d7-461a-9af9-22aa4abff68f", "8e37e627-25de-42cf-83df-4bae958d33de"]
  ],
  "generateAccessKey": true,
  "imageUrl": "https://amazon.com/image.png",
  "leaderboardStat": "kills",
  "matchesMax": 1,
  "matchesPerPlayer": 1,
  "metadata": "{\"stage\": 5, \"difficulty\": 9}",
  "playerAttemptsPerMatch": 100,
  "playersPerMatch": 500,
  "prizeBundles": [
    {
      "prizeIds": [
        "0031dc56-43e5-440f-9e05-ca747c28150e",
        "a6c0bc2a-d04f-449b-aa11-326072610592"
      ],
      "rankFrom": 1,
      "rankTo": 3,
      "title": "Prize Title",
      "description": "Prize Description",
      "imageUrl": "https://s3.amazonaws.com/tournament-prizes/Prize-Item-1.png"
    },
    {
      "prizeIds": [ "a6c0bc2a-d04f-449b-aa11-326072610592" ],
      "rankFrom": 4,
      "rankTo": 10,
      "title": "Prize Title #2",
      "description": "Prize Description #2",
      "imageUrl": "https://s3.amazonaws.com/tournament-prizes/Prize-Item-2.png"
    }
  ],
  "scoreType": "INDIVIDUAL",
  "subtitle": "Tournament Subtitle",
  "title": "Tournament Title",
  "winType": "HIGHEST",
  "releaseType":"MANUAL"
}

Example HTTP response (with participantType `INDIVIDUAL`)

Response 200

{
  "accessKey": "HDLD",
  "countryCodes": [
    "US", "CA"
  ],
  "dateEnd": 1515119589135,
  "dateStart": 1515105189135,
  "description": "Tournament description",
  "entryRequirements": [
    [ "99208d38-cac9-45fe-8bfd-954ff7e3ae11" ],
    [ "35831019-b1d7-461a-9af9-22aa4abff68f", "8e37e627-25de-42cf-83df-4bae958d33de" ]
  ],
  "visibilityRequirements": [
    [ "99208d38-cac9-45fe-8bfd-954ff7e3ae11" ],
    [ "35831019-b1d7-461a-9af9-22aa4abff68f", "8e37e627-25de-42cf-83df-4bae958d33de" ]
  ],
  "imageUrl": "https://amazon.com/image.png",
  "leaderboardStat": "kills",
  "matchesMax": 1,
  "matchesPerPlayer": 1,
  "metadata": "{\"stage\": 5, \"difficulty\": 9}",
	"participantType": "INDIVIDUAL",
  "playerAttemptsPerMatch": 100,
  "playersPerMatch": 500,
  "prizeBundles": [
    {
      "prizeIds": [
        "0031dc56-43e5-440f-9e05-ca747c28150e",
        "a6c0bc2a-d04f-449b-aa11-326072610592"
      ],
      "rankFrom": 1,
      "rankTo": 3,
      "title": "Prize Title",
      "description": "Prize Description",
      "imageUrl": "https://s3.amazonaws.com/tournament-prizes/Prize-Item-1.png"
    },
    {
      "prizeIds": [ "a6c0bc2a-d04f-449b-aa11-326072610592" ],
      "rankFrom": 4,
      "rankTo": 10,
      "title": "Prize Title #2",
      "description": "Prize Description #2",
      "imageUrl": "https://s3.amazonaws.com/tournament-prizes/Prize-Item-2.png"
    }
  ],
  "scoreType": "INDIVIDUAL",
  "subtitle": "Tournament Subtitle",
  "tournamentId": "1fd35e57-ad7a-49b9-8739-c6f64f55ae63",
  "title": "Tournament Title",
  "winType": "HIGHEST",
  "releaseType":"MANUAL"
}

Example HTTP request (for participantType `TEAM`)

Request

POST /tournaments
Content-Type: application/json
X-Api-Key: d2d0b961-a5ce-45c7-9dbe-a63061ee229c

Request body

{
  "dateEnd": 1515119589135,
  "dateStart": 1515105189135,
  "description": "Tournament description",
  "entryRequirements": [
    ["99208d38-cac9-45fe-8bfd-954ff7e3ae11"],
    ["35831019-b1d7-461a-9af9-22aa4abff68f", "8e37e627-25de-42cf-83df-4bae958d33de"]
  ],
  "visibilityRequirements": [
    ["99208d38-cac9-45fe-8bfd-954ff7e3ae11"],
    ["35831019-b1d7-461a-9af9-22aa4abff68f", "8e37e627-25de-42cf-83df-4bae958d33de"]
  ],
  "imageUrl": "https://amazon.com/image.png",
  "leaderboardStat": "kills",
  "playerAttemptsMax": 100,
  "prizeBundles": [
    {
      "prizeIds": [
        "0031dc56-43e5-440f-9e05-ca747c28150e",
        "a6c0bc2a-d04f-449b-aa11-326072610592"
      ],
      "rankFrom": 1,
      "rankTo": 3,
      "title": "Prize Title",
      "description": "Prize Description",
      "imageUrl": "https://s3.amazonaws.com/tournament-prizes/Prize-Item-1.png"
    },
    {
      "prizeIds": [ "a6c0bc2a-d04f-449b-aa11-326072610592" ],
      "rankFrom": 4,
      "rankTo": 10,
      "title": "Prize Title #2",
      "description": "Prize Description #2",
      "imageUrl": "https://s3.amazonaws.com/tournament-prizes/Prize-Item-2.png"
    }
  ],
  "scoreType": "INDIVIDUAL",
  "subtitle": "Tournament Subtitle",
  "title": "Tournament Title",
  "teamSizeMin": 5,
  "teamSizeMax": 5
}

Example HTTP response (with participantType `TEAM`)

Response 200

{
  "dateEnd": 1515119589135,
  "dateStart": 1515105189135,
  "description": "Tournament description",
  "entryRequirements": [
    [ "99208d38-cac9-45fe-8bfd-954ff7e3ae11" ],
    [ "35831019-b1d7-461a-9af9-22aa4abff68f", "8e37e627-25de-42cf-83df-4bae958d33de" ]
  ],
  "visibilityRequirements": [
    [ "99208d38-cac9-45fe-8bfd-954ff7e3ae11" ],
    [ "35831019-b1d7-461a-9af9-22aa4abff68f", "8e37e627-25de-42cf-83df-4bae958d33de" ]
  ],
  "imageUrl": "https://amazon.com/image.png",
  "leaderboardStat": "kills",
  "matchesMax": 1,
  "matchesPerPlayer": 1,
  "metadata": "{\"stage\": 5, \"difficulty\": 9}",
	"participantType": "TEAM",
  "playerAttemptsPerMatch": 100,
  "playersPerMatch": 1000000000,
  "prizeBundles": [
    {
      "prizeIds": [
        "0031dc56-43e5-440f-9e05-ca747c28150e",
        "a6c0bc2a-d04f-449b-aa11-326072610592"
      ],
      "rankFrom": 1,
      "rankTo": 3,
      "title": "Prize Title",
      "description": "Prize Description",
      "imageUrl": "https://s3.amazonaws.com/tournament-prizes/Prize-Item-1.png"
    },
    {
      "prizeIds": [ "a6c0bc2a-d04f-449b-aa11-326072610592" ],
      "rankFrom": 4,
      "rankTo": 10,
      "title": "Prize Title #2",
      "description": "Prize Description #2",
      "imageUrl": "https://s3.amazonaws.com/tournament-prizes/Prize-Item-2.png"
    }
  ],
  "scoreType": "INDIVIDUAL",
  "subtitle": "Tournament Subtitle",
  "tournamentId": "1fd35e57-ad7a-49b9-8739-c6f64f55ae63",
  "title": "Tournament Title",
  "winType": "HIGHEST",
  "releaseType":"AUTO",
  "teamSizeMin": 5,
  "teamSizeMax": 5
}

Add Tournament Series

POST /tournaments/series

Description

Create a series of recurring tournaments. Series is currently not supported for team tournaments.

Parameters

Type	Name	Description	Schema
Header	x-api-key optional	Admin API key. This is provided when you register your game.	string
Body	addTournamentSeriesRequest optional	JSON representation of AddTournamentSeriesRequest	AddTournamentSeriesRequest

Responses

HTTP Code	Description	Error Codes	Schema
200	Successfully created the tournament series.	None	AddTournamentSeriesResponse
400	Invalid request parameters.	[3]	No Content
403	Invalid x-api-key. Provide a valid Admin API Key in the x-api-key header.	[1]	No Content

See Error Codes for error code details.

Consumes

application/json

Produces

application/json

Example HTTP request

Request

POST /tournaments/series
Content-Type: application/json
X-Api-Key: d2d0b961-a5ce-45c7-9dbe-a63061ee229c

Request body

{
    "dateStartList": [
        1520370000000,
        1520456400000
    ],
    "numOfOccurrences": 2,
    "duration": 3600000,
    "cadence": 604800000,
    "description": "Tournament description",
    "leaderboardStat": "kills",
    "matchesMax": 1,
    "matchesPerPlayer": 1,
    "playerAttemptsPerMatch": 1,
    "playersPerMatch": 1,
    "subtitle": "Tournament Subtitle",
    "title": "Tournament Title",
    "releaseType": "manual"
}

Example HTTP response

Response 200

{
    "seriesId": "f376b33a-345a-4e98-ac00-911687704045",
    "tournamentIds": [
        "40fdc6e7-347e-4118-bb89-6f6d9f41a331",
        "17f93537-00af-4add-9ccf-3978845ce850"
    ],
    "leaderboardStat": "kills",
    "firstTournamentStartDate": 1520370000000,
    "lastTournamentEndDate": 1520460000000,
    "title": "Tournament Title",
    "subtitle": "Tournament Subtitle",
    "description": "Tournament description",
    "winType": "HIGHEST",
    "matchesMax": 1,
    "playersPerMatch": 1,
    "matchesPerPlayer": 1,
    "playerAttemptsPerMatch": 1,
    "scoreType": "INDIVIDUAL",
    "releaseType": "MANUAL"
}

Close Tournament

POST /tournaments/{tournamentId}/close

Description

Manually close a tournament.

Parameters

Type	Name	Description	Schema
Header	X-Api-Key required	Admin API key. This is provided when you register your game.	string
Path	tournamentId required	The identifier of the tournament to close manually.	string

Responses

HTTP Code	Description	Error Codes	Schema
202	Successfully accepted the request to close the tournament asynchronously.	None	No Content
400	Invalid request parameters.	[3]	No Content
403	Invalid x-api-key. Provide a valid Admin API Key in the x-api-key header.	[1]	No Content
404	The tournament with the provided 'tournamentId' could not be found.	[200]	No Content
409	Can happen for multiple reasons, please refer to the list of error codes.	[217, 218, 219]	No Content

See Error Codes for error code details.

Example HTTP request

Request

POST /tournaments/54d8fd8d-e349-49d8-902c-0558365ac22b/close
X-Api-Key: d2d0b961-a5ce-45c7-9dbe-a63061ee229c

Example HTTP response

Response 202 (releaseType = AUTO)

{
     "message": "Request received to close tournament 54d8fd8d-e349-49d8-902c-0558365ac22b. Processing tournament to rank players and award prizes (if any)."
}

Response 202 (releaseType = MANUAL)

{
    "message": "Request received to close tournament 54d8fd8d-e349-49d8-902c-0558365ac22b. Please wait while we process the tournament to rank players. To complete the tournament and award prizes (if any) call closeTournament again."
}

Delete Upcoming Tournament

DELETE /tournaments/{tournamentId}

Description

Deletes a tournament that has not started yet.

Parameters

Type	Name	Description	Schema
Header	X-Api-Key required	Admin API key. This is provided when you register your game.	string
Path	tournamentId required	The identifier of the tournament to close manually.	string

Responses

HTTP Code	Description	Error Codes	Schema
200	Successfully deleted the provided 'tournamentId'.	None	No Content
400	Invalid request parameters.	[3]	No Content
403	Invalid x-api-key. Provide a valid Admin API Key in the x-api-key header.	[1]	No Content
404	The tournament with the provided 'tournamentId' could not be found.	[200]	No Content
409	Cannot perform action on provided 'tournamentId' because it has already started.	[204]	No Content

See Error Codes for error code details.

Example HTTP request

Request

DELETE /tournament/54d8fd8d-e349-49d8-902c-0558365ac22b
X-Api-Key: d2d0b961-a5ce-45c7-9dbe-a63061ee229c

Get Prize List

GET /prizes

Description

Get the list of available prizes for a game based on its admin API key. Prizes that have expired, or one-time prizes that have already been used, will not be returned.

Parameters

Type	Name	Description	Schema
Header	Content-Type required	`application/json`	string
Header	X-Api-Key required	Admin API key. This is provided when you register your game.	string

Responses

HTTP Code	Description	Schema
200	Successfully added at least one prize.	GetPrizeListResponse
400	Invalid request parameters.	No Content
403	Forbidden. Invalid API Key.	No Content

Produces

application/json

Example HTTP request

Request

GET /prizes
Content-Type: application/json
X-Api-Key: d2d0b961-a5ce-45c7-9dbe-a63061ee229c

Example HTTP response

Response 200

{
  "prizes": [
    {
      "description": "Live forever with this bundle of health potions.",
      "imageUrl": "https://s3.amazonaws.com/tournament-prizes/Prize-Item-1.png",
      "prizeId": "65d738d1-7e81-450e-97c0-79352284145a",
      "title": "100 Health Potions",
      "prizeInfoType": "VENDOR"
    },
    {
      "description": "This chest contains better loot than the Silver Chest.",
      "imageUrl": "https://s3.amazonaws.com/tournament-prizes/Prize-Item-1.png",
      "prizeId": "caf9a785-d6e8-4990-bf63-49f7d485a8d9",
      "title": "Golden Chest",
      "prizeInfoType": "VENDOR"
    }
  ]
}

Delete Prize

DELETE /prizes/{prizeId}

Description

Delete an in-app prize based on game's admin API key. This operation will make a deleted prize become unavailable for any tournaments created afterwards but will not affect any of the past, on-going and upcoming tournaments that have used this prize.

Parameters

Type	Name	Description	Schema
Header	Content-Type required	`application/json`	string
Header	X-Api-Key required	Admin API key. This is provided when you register your game.	string
Path	prizeId required	The ID of the in-app prize to delete.	string

Responses

HTTP Code	Description	Schema
200	Successfully delete prize.	No Content
400	Invalid request parameters.	No Content
403	Forbidden. Invalid API Key or prize cannot be deleted	No Content
404	Invalid prizeId.	No Content

Example HTTP request

Request

DELETE /prizes/a3a631e1-6ece-4ab6-ae6e-91f157e16232
Content-Type: application/json
X-Api-Key: d2d0b961-a5ce-45c7-9dbe-a63061ee229c

Get Requirement List

GET /requirements

Description

Get a list of requirements added for use against tournaments.

Parameters

Type	Name	Description	Schema
Header	Content-Type required	`application/json`	string
Header	X-Api-Key required	Admin API key. This is provided when you register your game.	string

Responses

HTTP Code	Description	Schema
200	Successfully added at least one requirement.	GetRequirementListResponse
400	Invalid request parameters.	No Content
403	Forbidden. Invalid API Key.	No Content

Produces

application/json

Example HTTP request

Request

POST /prizes
Content-Type: application/json
X-Api-Key: d2d0b961-a5ce-45c7-9dbe-a63061ee229c

Example HTTP response

Response 200

{
  "requirements": [
    {
      "key": "status",
      "name": "Player is VIP",
      "requirementId": "f17abf7f-df0a-4b78-b28a-ddad30f9abf7",
      "type": "value",
      "value": "VIP"
    },
    {
      "description": "The player has a skill between 0 and 10.",
      "high": 10,
      "key": "League",
      "low": 0,
      "name": "Player is a beginner",
      "requirementId": "d00d6524-9aaf-4c57-aee3-ec5fe07946ce",
      "type": "range"
    },
    {
      "name": "Greater Seattle Area",
      "description": "The GPS coordinates of the player is located in the Greater Seattle Area",
      "type": "gps",
      "key": "gpsCoordinates",
      "permittedAreas": [
        {
          "gpsCoordinates": {
            "latitude": 47.60604,
            "longitude": -122.3328
          },
          "radius": 10,
          "radiusUnits": "KILOMETERS"
        }
      ],
      "requirementId": "7ccbfba8-61b8-4abe-a8f1-59d54e324312",
    }
  ]
}

Register Player

POST /players/register

Description

Similar to the Game API, Register Player adds a player (and their device) to Amazon Leaderboards and Tournaments, conducts a key exchange, and returns an encrytedToken. However, with the Admin API version, you can also provide a vendorPlayerId to allow multi device account registration. For more information see Register Player for the Game API.

For the new games that are registered after Aug 14, 2018, the Leaderboards and Tournaments advanced security requires generating longer keys (2048 bits) for the players and use OAEP (a padding mechanism) while encrypting and decrypting. These games should only provide 2048-bit client public key and encrypt it with OAEP using the game public key provided during game registration. Cryptography code samples can be found here.

Games that registered with us before Aug 15, 2018 and opted for advanced security, can continue sending 1024-bit client public key and encrypt it without OAEP.

Parameters

Type	Name	Description	Schema
Header	Content-Type required	`application/json`	string
Header	X-Api-Key required	Admin API key. This is provided when you register your game.	string
Body	registerPlayerRequest required	Information required to register a player.	RegisterPlayerRequest

Responses

HTTP Code	Description	Error Codes	Schema
200	Successfully registered the player.	None	RegisterPlayerResponse
400	Invalid request parameters.	[3, 100, 101, 102, 103, 104]	No Content
401	Invalid x-api-key. Provide a valid Admin API Key in the x-api-key header.	[1]	No Content
403	Invalid x-api-key. Provide a valid Admin API Key in the x-api-key header.	[1]	No Content

See Error Codes for error code details.

Consumes

application/json

Produces

application/json

Example HTTP request

Request

POST /players/register
Content-Type: application/json
X-Api-Key: d2d0b961-a5ce-45c7-9dbe-a63061ee229c

Request body

{
  "encryptedPayload" : "Iq6nXfcoDYQEKZEDBhiHefKJLn2Q70iU09DKD7lMsEyFwUguI5w5+WYkM4b0MBfagRFsOltocwsyy0ujzYJ7F3QyRjCIdUc0IP8P6OQmU6fuU43u/AKpNLT4HphCzFOFiQwY4Jf6eIyfaClBiuZkB1apXz1qAhaQd5PdrUQ1JTT2dmEIQZF+lXz1bLpOBDbuKMcOVW55xn7CXC0LcyX6Y58ydZ2bFuNFNchY/mK5ubsbvg+b/8k1cdZDS7dtT9LEwgHUI77ZlmyU+dE/91BlM2nRuqyK8yCv+juA4/MvQ+nSeXtGZROkFZmmX45kh3ngrCQp1dqDVWHA749fFew0pg=="
}

Example HTTP response

Response 200

{
  "encryptedPlayerToken" : "gIBkQDL6yDAcMC5eMnDBoC+MypR6fbmf4oTEtzDAh27LOhLeO5tow4gXIQ/0rmzom+IqtXVZxtRUJAhLIoWbEwtHJ4Xze8LVU3rXZ1NyJX26tE6pu9SvE5CARcpDJtRc20EGQ965fxt6PWlkFwvn4BJkHzXQ/pEGONpEDTKuhXM="
}

Definitions

UpdateGameRequest

Name	Description	Schema
gameStats required	A list of stats to add to the game to be used for score submission. Example : `[ "kills", "assists", "gold"]`	< string > array

TeamPlayerListRequest

Name	Description	Schema
externalPlayerIds required	A list of player IDs to add or remove from a team. Example : `[ "b1f2af5b-8bba-480a-831f-0a5f1af94f1c" ]`	< string > array

AddTeamPlayerListResponse

Name	Description	Schema
teamSpotsRemaining required	The number of spots remaining after adding or removing players from a team. Example : `3`	integer (int32)

RemoveTeamPlayerListResponse

Name	Description	Schema
teamSpotsRemaining required	The number of spots remaining after adding or removing players from a team. Example : `3`	integer (int32)
failedExternalPlayerIds optional	The players that were requested, but unable to be removed do to various reasons – see Get Tournament Details for more information. The number of spots remaining after adding or removing players from a team. Example : `[ "b1f2af5b-8bba-480a-831f-0a5f1af94f1c" ]`	< string > array

AddPrizeListRequest

Name	Description	Schema
prizes required	The list of in-app prizes to add to Amazon Leaderboards and Tournaments.	< AddPrizeListRequest_Prize > array

AddPrizeListRequest_Prize

Name	Description	Schema
description required	The description of the prize. Example : `"This chest contains better loot than the Silver Chest."`	string
imageUrl optional	The url for the prize image. Example : `"https://amazon.com/image.png"`	string
title required	The title of the prize. Example : `"Gold Chest"`	string
prizeInfo required	Information for claiming a prize when awarded. Example : `"GOLD_CHEST_0123"`	string

AddPrizeListResponse

Name	Description	Schema
addedPrizes required	The list of prizes added successfully to Amazon Leaderboards and Tournaments.	< AddPrizeListResponse_Prize > array
failedPrizes optional	The list of prizes that failed to add to Amazon Leaderboards and Tournaments.	< AddPrizeListResponse_Prize > array

AddPrizeListResponse_Prize

Name	Description	Schema
description required	The description of the prize. Example : `"This chest contains better loot than the Silver Chest."`	string
imageUrl optional	The url for the prize image. Example : `"https://amazon.com/image.png"`	string
prizeId optional	The prize identifier which may be blank if the prize failed to add. Example : `eed51953-530d-4516-92c0-401c0995c21d`	string
title required	The title of the prize. Example : `"Gold Chest"`	string
prizeInfo required	Information for claiming a prize when awarded. Example : `"GOLD_CHEST_0123"`	string
prizeInfoType required	Describes what is contained in `prizeInfo` Values : `"VENDOR"`	string

AddRequirementListRequest

Name	Description	Schema
requirements required	The list of requirements to add to Amazon Leaderboards and Tournaments, which can be of multiple type.	< RequirementListType_Value \| RequirementListType_Range \| RequirementListType_Contains \| RequirementListType_GPS \| RequirementListType_Regex > array

RequirementListType_GPS

Name	Description	Schema
name required	The name of the requirement. Example : `"Greater Seattle Area"`	string
description optional	The description of the requirement. Example : `"The GPS coordinates of the player is located in the Greater Seattle Area"`	string
type required	The type of the requirement. Example : `"gps"`	string
key required	The key of the requirement. Example : `"gpsCoordinates"`	string
permittedAreas required	The permitted areas of the requirement.	< RequirementList_PermittedArea > array

RequirementListType_Range

Name	Description	Schema
name required	The name of the requirement. Example : `"Player is a beginner"`	string
description optional	The description of the requirement. Example : `"The player has a skill between 0 and 10."`	string
type required	The type of the requirement. Example : `"range"`	string
high required	The high range (inclusive) of the requirement. Example : `10`	number (double)
key required	The key of the requirement. Example : `"skill"`	string
low required	The low range (inclusive) of the requirement. Example : `0`	number (double)

RequirementListType_Regex

Name	Description	Schema
name required	The name of the requirement. Example : `"Number Players"`	string
description optional	The description of the requirement. Example : `"The player name contains numbers only."`	string
type required	The type of the requirement. Example : `"regex"`	string
key required	The key of the requirement. Example : `"name"`	string
value required	The value of the requirement. Example : `"^[0-9]+$"`	string

RequirementListType_Value

Name	Description	Schema
name required	The name of the requirement. Example : `"Player is VIP"`	string
description optional	The description of the requirement. Example : `"The player has VIP status."`	string
type required	The type of the requirement. Example : `"value"`	string
key required	The key of the requirement. Example : `"status"`	string
value required	The value of the requirement. Example : `"VIP"`	string

RequirementListType_Contains

Name	Description	Schema
name required	The name of the requirement. Example : `"Player Origin"`	string
description optional	The description of the requirement. Example : `"Country the player resides in."`	string
type required	Contains can match the provided requirement from a list. Example : `"contains"`	string
key required	The key of the requirement. Example : `"origin"`	string
values required	List of possible values (converted uppercase). Example : `["US", "IN", "FR"]`	string

AddRequirementListResponse

Name	Description	Schema
addedRequirements required	The list of requirements added successfully to Amazon Leaderboards and Tournaments.	< RequirementListResponse_Requirement > array
failedRequirements optional	The list of requirements that failed to add to Amazon Leaderboards and Tournaments.	< RequirementListResponse_Requirement > array

AddIndividualTournamentRequest

Name	Description	Schema
participantType optional	The type of participants that will be in the tournament. For an individual tournament use `INDIVIDUAL`, For a team tournament please see AddTeamTournamentRequest.	string
countryCodes optional	List of countries players can participate from. Value must be a list of valid ISO 3166-1 Alpha-2 country codes. Example : `["US", "CA"]`	< string > array
dateEnd required	The timestamp for when the tournament should end. Example : `1513943202000`	integer (int64)
dateStart required	The timestamp for when the tournament should start. Example : `1513899902000`	integer (int64)
description optional	The description of the tournament. Example : `"Compete against the best players and see if you can come out on top!"`	string
entryRequirements optional	Requirement set used to determine whether a player may enter this tournament in the form of a list of list of requirement ids for the tournament. The inner level list requirement ids are AND together and the outer level list requirement ids are OR together. Example : `[ ["99208d38-cac9-45fe-8bfd-954ff7e3ae11"], ["35831019-b1d7-461a-9af9-22aa4abff68f", "8e37e627-25de-42cf-83df-4bae958d33de"] ]`	< < string > array > array
visibilityRequirements optional	Requirement set used to determine whether a player may see this tournament in the form of a list of list of requirement ids for the tournament. The inner level list requirement ids are AND together and the outer level list requirement ids are OR together. Example : `[ ["99208d38-cac9-45fe-8bfd-954ff7e3ae11"], ["35831019-b1d7-461a-9af9-22aa4abff68f", "8e37e627-25de-42cf-83df-4bae958d33de"] ]`	< < string > array > array
generateAccessKey optional	Flag to determine whether an access key should be generated or not. Example : `false`	boolean
imageUrl optional	The url for the tournament image. Example : `"https://amazon.com/image.png"`	string
leaderboardStat optional	The stat to use to rank the leaderboard for the tournament. Example : `kills`	string
matchesMax optional	The max number of matches for the tournament. Limit is 50. Defaults to `1`. Example : `1`	integer (int16)
matchesPerPlayer optional	The max number of matches a player can join. Defaults to `1`. Example : `3`	integer (int16)
metadata optional	Any metadata to associate with the tournament. Example : `"{\"stage\": 5, \"difficulty\": 9}"`	string
playerAttemptsPerMatch optional	The maximum number of player attempts per match. Defaults to `1,000,000,000`. Example : `5`	integer (int32)
playersPerMatch optional	The maximum number of players per match. Defaults to `1,000,000,000`. Example : `100`	integer (int32)
prizeBundles optional	The list of prize bundles to award winning players.	< AddTournament_PrizeBundle > array
scoreType optional	Indicate if the scoring model is `INDIVIDUAL` or `CUMULATIVE`. `INDIVIDUAL` will take the best score submitted, where as `CUMULATIVE` will sum all submitted scores together. Using `CUMULATIVE` in conjunction with positive and negative scores, a player can be brought up or down a leaderboard, supporting use cases for "League Play" determined by wins and loses or "Elo" ratings in games. Defaults to `INDIVIDUAL`. Example : `"INDIVIDUAL"`	string
subtitle optional	The subtitle of the tournament. Example : `"Are you the best of the best?"`	string
title required	The title of the tournament. Example : `"Championship Tournament!"`	string
winType optional	Indicate if the `LOWEST` or `HIGHEST` score will win. Defaults to `HIGHEST.` Example : `"HIGHEST"`	string
releaseType optional	Indicate if the prizes for this tournament should be released automatically (`AUTO`) or manually (`MANUAL`) by the developer. Defaults to `AUTO`. Example : `"AUTO"`	string

AddTeamTournamentRequest

Name	Description	Schema
participantType required	The type of participants that will be in the tournament. For a team tournament use `TEAM`, For an individual tournament please see AddIndividualTournamentRequest.	string
countryCodes optional	List of countries players can participate from. Value must be a list of valid ISO 3166-1 Alpha-2 country codes. Example : `["US", "CA"]`	< string > array
dateEnd required	The timestamp for when the tournament should end. Example : `1513943202000`	integer (int64)
dateStart required	The timestamp for when the tournament should start. Example : `1513899902000`	integer (int64)
description optional	The description of the tournament. Example : `"Compete against the best players and see if you can come out on top!"`	string
entryRequirements optional	Requirement set used to determine whether a player may enter this tournament in the form of a list of list of requirement ids for the tournament. The inner level list requirement ids are AND together and the outer level list requirement ids are OR together. Example : `[ ["99208d38-cac9-45fe-8bfd-954ff7e3ae11"], ["35831019-b1d7-461a-9af9-22aa4abff68f", "8e37e627-25de-42cf-83df-4bae958d33de"] ]`	< < string > array > array
visibilityRequirements optional	Requirement set used to determine whether a player may see this tournament in the form of a list of list of requirement ids for the tournament. The inner level list requirement ids are AND together and the outer level list requirement ids are OR together. Which team a player is in also determines visiblity. Example : `[ ["99208d38-cac9-45fe-8bfd-954ff7e3ae11"], ["35831019-b1d7-461a-9af9-22aa4abff68f", "8e37e627-25de-42cf-83df-4bae958d33de"] ]`	< < string > array > array
generateAccessKey optional	Flag to determine whether an access key should be generated or not. Example : `false`	boolean
imageUrl optional	The url for the tournament image. Example : `"https://amazon.com/image.png"`	string
leaderboardStat optional	The stat to use to rank the leaderboard for the tournament. Example : `kills`	string
metadata optional	Any metadata to associate with the tournament. Example : `"{\"stage\": 5, \"difficulty\": 9}"`	string
playerAttemptsMax optional	The maximum attempts for a player to submit a score for their team. Defaults to 1. Example : `5`	integer (int32)
prizeBundles optional	The list of prize bundles to award winning players.	< AddTournament_PrizeBundle > array
teamSizeMin optional	The minimum team size allowed to enter the tournament. Will only be provided for a team tournament. Example : `"3"`	string
teamSizeMax optional	The maximum team size allowed to enter the tournament. Will only be provided for a team tournament. Example : `"5"`	string
scoreType optional	Indicate if the scoring model is `INDIVIDUAL` or `CUMULATIVE`. `INDIVIDUAL` will take the best score submitted, where as `CUMULATIVE` will sum all submitted scores together. Using `CUMULATIVE` in conjunction with positive and negative scores, a player can be brought up or down a leaderboard, supporting use cases for "League Play" determined by wins and loses or "Elo" ratings in games. Defaults to `INDIVIDUAL`. Example : `"INDIVIDUAL"`	string
subtitle optional	The subtitle of the tournament. Example : `"Are you the best of the best?"`	string
title required	The title of the tournament. Example : `"Championship Tournament!"`	string
winType optional	Indicate if the `LOWEST` or `HIGHEST` score will win. Defaults to `HIGHEST`. Example : `"HIGHEST"`	string
releaseType optional	Indicate if the prizes for this tournament should be released automatically (`AUTO`) or manually (`MANUAL`) by the developer. Defaults to `AUTO`. Example : `"AUTO"`	string

AddTournamentResponse

Name	Description	Schema
accessKey optional	Access key value needed to enter the tournament. Example : `"BRTC"`	string
countryCodes optional	List of countries players can participate from. The value depends on countryCodes in request. Value will be a list of valid ISO 3166-1 Alpha-2 country codes. Example : `["US", "CA"]`	< string > array
dateEnd required	The timestamp for when the tournament should end. Example : `1513943202000`	integer (int64)
dateStart required	The timestamp for when the tournament should start. Example : `1513899902000`	integer (int64)
description required	The title of the tournament. Example : `"Compete against the best players and see if you can come out on top!"`	string
entryRequirements optional	Requirement set used to determine whether a player may enter this tournament in the form of a list of list of requirement ids for the tournament. The inner level list requirement ids are AND together and the outer level list requirement ids are OR together. Example : `[ ["99208d38-cac9-45fe-8bfd-954ff7e3ae11"], ["35831019-b1d7-461a-9af9-22aa4abff68f", "8e37e627-25de-42cf-83df-4bae958d33de"] ]`	< < string > array > array
visibilityRequirements optional	Requirement set used to determine whether a player may see this tournament in the form of a list of list of requirement ids for the tournament. The inner level list requirement ids are AND together and the outer level list requirement ids are OR together. Example : `[ ["99208d38-cac9-45fe-8bfd-954ff7e3ae11"], ["35831019-b1d7-461a-9af9-22aa4abff68f", "8e37e627-25de-42cf-83df-4bae958d33de"] ]`	< < string > array > array
imageUrl optional	The url for the tournament image. Example : `"https://amazon.com/image.png"`	string
leaderboardStat optional	The stat to use to rank the leaderboard for the tournament. Example : `kills`	string
matchesMax required	The max number of matches for the tournament. Limit is 50. Example : `1`	integer (int16)
matchesPerPlayer required	The max number of matches a player can join. Example : `3`	integer (int16)
metadata optional	Any metadata to associate with the tournament. Example : `"{\"stage\": 5, \"difficulty\": 9}"`	string
participantType required	The type of participants that will be in the tournament. Example : `"INDIVIDUAL"`	string
playerAttemptsPerMatch optional	The maximum number of player attempts per match. Example : `5`	integer (int32)
playersPerMatch required	The maximum number of players per match. Example : `100`	integer (int32)
prizeBundles required	The list of prize bundles to award winning players.	< AddTournament_PrizeBundle > array
teamSizeMin optional	The minimum team size allowed to enter the tournament. Will only be provided for a team tournament. Example : `"3"`	string
teamSizeMax optional	The maximum team size allowed to enter the tournament. Will only be provided for a team tournament. Example : `"5"`	string
scoreType optional	Indicate if the scoring model is `INDIVIDUAL` or `CUMULATIVE`. `INDIVIDUAL` will take the best score submitted, where as `CUMULATIVE` will sum all submitted scores together. Using `CUMULATIVE` in conjunction with positive and negative scores, a player can be brought up or down a leaderboard, supporting use cases for "League Play" determined by wins and loses or "Elo" ratings in games. Defaults to `INDIVIDUAL`. Example : `"INDIVIDUAL"`	string
subtitle optional	The subtitle of the tournament. Example : `"Are you the best of the best?"`	string
title required	The title of the tournament. Example : `"Championship Tournament!"`	string
tournamentId required	The id of the tournament. Example : `"1fd35e57-ad7a-49b9-8739-c6f64f55ae63"`	string
winType optional	Indicate if the `LOWEST` or `HIGHEST` score will win. Example : `"HIGHEST"`	string
releaseType optional	Indicate if the prizes for this tournament should be released automatically (`AUTO`) or manually (`MANUAL`) by the developer. Example : `"AUTO"`	string

AddTournament_PrizeBundle

Name	Description	Schema
description optional	The description of the tournament. Example : `"Top 3 players will win this!"`	string
imageUrl optional	The image url for the prize bundle. Example : `"https://amazon.com/image.png"`	string
prizeIds required	List of prize ids awarded in bundle. Example : `[be2f5858-5d90-41aa-844b-8862591671ab, 2cbbf9e1-772a-4d01-8ba5-b336c79c8c30]`	< string > array
rankFrom required	The highest rank to award the prizes to (inclusive.) Example : `1`	integer (int32)
rankTo required	The lowest rank to award the prizes to (inclusive.) Example : `3`	integer (int32)
title required	The title of the prize bundle. Example : `"Gold Chest"`	string

AddTournamentSeriesRequest

Name	Description	Schema
dateStartList required	List of timestamp to create tournaments startDates. Example : `[1513943202000]`	integer (int64)
dateEnd optional	The timestamp for when the series should end. Either dateEnd or numOfOccurrences need to be set. Example : `1513899902000`	integer (int64)
numOfOccurrences optional	The number of tournament occurrences in the series. Either numOfOccurrences or dateEnd need to be set. Example : `12`	integer (int64)
cadence required	The tournament series frequency every hour/day/week/month… Example : `86400000`	integer (int64)
duration required	The tournament duration in milliseconds. Example : `3600000`	integer (int64)
description required	The description of the tournament. Example : `"Compete against the best players and see if you can come out on top!"`	string
entryRequirements optional	Requirement set used to determine whether a player may enter this tournament in the form of a list of list of requirement ids for the tournament. The inner level list requirement ids are AND together and the outer level list requirement ids are OR together. Example : `[ ["99208d38-cac9-45fe-8bfd-954ff7e3ae11"], ["35831019-b1d7-461a-9af9-22aa4abff68f", "8e37e627-25de-42cf-83df-4bae958d33de"] ]`	< < string > array > array
visibilityRequirements optional	Requirement set used to determine whether a player may see this tournament in the form of a list of list of requirement ids for the tournament. The inner level list requirement ids are AND together and the outer level list requirement ids are OR together. Example : `[ ["99208d38-cac9-45fe-8bfd-954ff7e3ae11"], ["35831019-b1d7-461a-9af9-22aa4abff68f", "8e37e627-25de-42cf-83df-4bae958d33de"] ]`	< < string > array > array
generateAccessKey optional	Flag to determine whether an access key should be generated or not. Example : `false`	boolean
imageUrl optional	The url for the tournament image. Example : `"https://amazon.com/image.png"`	string
leaderboardStat optional	The stat to use to rank the leaderboard for the tournament. Example : `kills`	string
matchesMax required	The max number of matches for the tournament. Limit is 50. Example : `1`	integer (int16)
matchesPerPlayer required	The max number of matches a player can join. Example : `3`	integer (int16)
metadata optional	Any metadata to associate with the tournament. Example : `"{\"stage\": 5, \"difficulty\": 9}"`	string
playerAttemptsPerMatch required	The maximum number of player attempts per match. Example : `5`	integer (int32)
playersPerMatch required	The maximum number of players per match. Example : `100`	integer (int32)
prizeBundles optional	The list of prize bundles to award winning players.	< AddTournament_PrizeBundle > array
scoreType optional	Indicate if the scoring model is `INDIVIDUAL` or `CUMULATIVE`. `INDIVIDUAL` will take the best score submitted, where as `CUMULATIVE` will sum all submitted scores together. Using `CUMULATIVE` in conjunction with positive and negative scores, a player can be brought up or down a leaderboard, supporting use cases for "League Play" determined by wins and loses or "Elo" ratings in games. Defaults to `INDIVIDUAL`. Example : `"INDIVIDUAL"`	string
subtitle optional	The subtitle of the tournament. Example : `"Are you the best of the best?"`	string
title required	The title of the tournament. Example : `"Championship Tournament!"`	string
winType optional	Indicate if the `LOWEST` or `HIGHEST` score will win. Defaults to `HIGHEST.` Example : `"HIGHEST"`	string
releaseType optional	Indicate if the prizes for this tournament should be released automatically (`AUTO`) or manually (`MANUAL`) by the developer. Defaults to `AUTO`. Example : `"AUTO"`	string

AddTournamentSeriesResponse

Name	Description	Schema
seriesId required	The series id of scheduled tournaments. Example : `"8a129f48-6dc6-4b27-9237-6729b1925db1"`	string
tournamentIds required	List of tournaments ids scheduled in a series. Example : `["fe2f5358-5d90-413a-844b-8833391671ab", "ccbbf9e1-242a-4d01-8ba5-j336c79c8c30"]`	< string > array
lastTournamentDateEnd required	The timestamp for when the last tournament in the series should end. Example : `1513943202000`	integer (int64)
firstTournamentDateStart required	The timestamp for when the first tournament in the series should start. Example : `1513899902000`	integer (int64)
accessKey optional	Access key value needed to enter the tournament. Example : `"BRTC"`	string
description required	The description of the tournament. Example : `"Compete against the best players and see if you can come out on top!"`	string
entryRequirements optional	Requirement set used to determine whether a player may enter this tournament in the form of a list of list of requirement ids for the tournament. The inner level list requirement ids are AND together and the outer level list requirement ids are OR together. Example : `[ ["99208d38-cac9-45fe-8bfd-954ff7e3ae11"], ["35831019-b1d7-461a-9af9-22aa4abff68f", "8e37e627-25de-42cf-83df-4bae958d33de"] ]`	< < string > array > array
visibilityRequirements optional	Requirement set used to determine whether a player may see this tournament in the form of a list of list of requirement ids for the tournament. The inner level list requirement ids are AND together and the outer level list requirement ids are OR together. Example : `[ ["99208d38-cac9-45fe-8bfd-954ff7e3ae11"], ["35831019-b1d7-461a-9af9-22aa4abff68f", "8e37e627-25de-42cf-83df-4bae958d33de"] ]`	< < string > array > array
imageUrl optional	The url for the tournament image. Example : `"https://amazon.com/image.png"`	string
leaderboardStat optional	The stat to use to rank the leaderboard for the tournament. Example : `kills`	string
matchesMax required	The max number of matches for the tournament. Limit is 50. Example : `1`	integer (int16)
matchesPerPlayer required	The max number of matches a player can join. Example : `3`	integer (int16)
metadata optional	Any metadata to associate with the tournament. Example : `"{\"stage\": 5, \"difficulty\": 9}"`	string
playerAttemptsPerMatch optional	The maximum number of player attempts per match. Example : `5`	integer (int32)
playersPerMatch required	The maximum number of players per match. Example : `100`	integer (int32)
prizeBundles required	The list of prize bundles to award winning players.	< AddTournament_PrizeBundle > array
scoreType optional	Indicate if the scoring model is `INDIVIDUAL` or `CUMULATIVE`. `INDIVIDUAL` will take the best score submitted, where as `CUMULATIVE` will sum all submitted scores together. Using `CUMULATIVE` in conjunction with positive and negative scores, a player can be brought up or down a leaderboard, supporting use cases for "League Play" determined by wins and loses or "Elo" ratings in games. Defaults to `INDIVIDUAL`. Example : `"INDIVIDUAL"`	string
subtitle optional	The subtitle of the tournament. Example : `"Are you the best of the best?"`	string
title required	The title of the tournament. Example : `"Championship Tournament!"`	string
winType optional	Indicate if the `LOWEST` or `HIGHEST` score will win. Example : `"HIGHEST"`	string
releaseType optional	Indicate if the prizes for this tournament should be released automatically (`AUTO`) or manually (`MANUAL`) by the developer. Example : `"AUTO"`	string

CreateTeamRequest

Name	Description	Schema
teamName optional	The name of the team. Example : `"Team Name"`	string
imageUrl optional	The image url for the team. Example : `"https://amazon.com/image.png"`	string
teamSizeMax required	The maximum number of players that can be in the team at any given time. Example : `5`	integer (int32)

CreateTeamResponse

Name	Description	Schema
teamId required	The ID of the team. Example : `"f9b12bf7-a50e-4cea-b320-e0814cf47616"`	string
teamName required	The name of the team. Example : `"Team Name"`	string
imageUrl optional	The image url for the team. Example : `"https://amazon.com/image.png"`	string
teamSizeMax required	The maximum number of players that can be in the team at any given time. Example : `5`	integer (int32)

GetPrizeListResponse

Name	Description	Schema
prizes required	The list of prizes in Amazon Leaderboards and Tournaments.	< GetPrizeListResponse_Prize > array

GetPrizeListResponse_Prize

Name	Description	Schema
description required	The description of the prize. Example : `"This chest contains better loot than the Silver Chest."`	string
imageUrl optional	The url for the prize image. Example : `"https://amazon.com/image.png"`	string
prizeId required	The prize identifier. Example : `eed51953-530d-4516-92c0-401c0995c21d`	string
title required	The title of the prize. Example : `"Gold Chest"`	string
prizeInfoType required	Describes what is contained in `prizeInfo` Values : `"VENDOR"`	string
dateOfExpiration optional	The date the prize expires and can no longer be used. Example : `1516654800000`	integer (int64)
cost optional	The cost of the prize per unit, in USD. Example : `99.99`	number (double)
countryCodes optional	List of countries players can redeem the prize. Value will be a list of valid ISO 3166-1 Alpha-2 country codes. Example : `["US", "CA"]`	< string > array
quantity optional	The quantity of the prize. Example : `10`	integer (int32)

GetRequirementListResponse

Name	Description	Schema
requirements required	The list of requirements added to Amazon Leaderboards and Tournaments, which can be of multiple type.	< RequirementListType_Value \| RequirementListType_Range \| RequirementListType_GPS \| RequirementListType_Regex > array

RegisterPlayerRequest

Name	Description	Schema
encryptedPayload optional	Client public key, created by the device, that is encrypted with OAEP using the game public key provided upon registering your game. It is only required if advanced security is enabled. Example : `"Iq6nXfcoDYQEKZED...749fFew0pg=="`	string
vendorPlayerId optional	Identifier that links a player across multiple devices. Example : `"hunkdory"`	string

RegisterPlayerResponse

Name	Description	Schema
encryptedPlayerToken optional	Encrypted player token. Player token is used for authenticating a player device. This will only be returned if advanced security is enabled. Decrypt with OAEP using the private key corresponding to the client public key that was provided in the request. Example : `"gIBkQDL6yDAcMC5e...ONpEDTKuhXM="`	string
playerToken optional	Used for authenticating a player device and will only be returned if advanced security is disabled. Example : `"e29ee83d-0d9f-4167-af1f-26e87f45ca74"`	string
externalPlayerId required	The Leaderboards and Tournaments player id for identifying this unique player. Example : `"445f49ac-b920-45b5-ae3b-4255cb9f5388"`	string

RequirementListResponse_Requirement

Name	Description	Schema
name required	The name of the requirement. Example : `"Player is VIP"`	string
description optional	The description of the requirement. Example : `"The player has VIP status."`	string
type required	The type of the requirement. Example : `"[VALUE, RANGE, REGEX, GPS]"`	string
key required	The key of the requirement. Example : `"status"`	string
value optional	The value of the requirement if Value or Regex type. Example : `"VIP"`	string
values optional	The values of the requirement if contains type. Example : `["US", "IN, "FR"]`	string
high optional	The high range (inclusive) of the requirement if Range type. Example : `10.5`	number (double)
low optional	The low range (inclusive) of the requirement if Range type. Example : `1`	number (double)
permittedAreas optional	The permitted areas of the requirement if GPS type.	< RequirementList_PermittedArea > array
requirementId optional	The requirement identifier which may be blank if the requirement failed to add. Example : `"d6924d17-ff9f-4e86-9a8f-1bb6b8f4d057"`	string

RequirementList_PermittedArea

Name	Description	Schema
gpsCoordinates required	The GPS coordinates of the permitted area.	RequirementList_GPSCoordinates
radius required	The radius around the GPS Coordinates that represents the permitted area. Example : `5.0`	number (double)
radiusUnits required	The unit distance of the radius value. Example : `["KILOMETERS", "MILES"]`	string

RequirementList_GPSCoordinates

Name	Description	Schema
latitude required	GPS longitude value in decimal degrees. North values are positive, south values are negative. Example : `47.60604`	number (double)
longitude required	GPS latitude value in decimal degrees. West values are positive, east values are negative. Example : `-122.3328`	number (double)

Admin API Reference

Overview

Version information

License information

URI scheme

Paths

Update Game

Description

Parameters

Responses

Consumes

Produces

Example HTTP request

Example HTTP response

Response 204

Add Prize List

Description

Parameters

Responses

Consumes

Produces

Example HTTP request

Request

Request body

Example HTTP response

Response 200

Add Requirement List

Description

Parameters

Responses

Consumes

Produces

Example HTTP request

Request

Request body

Example HTTP response

Response 200

Create Team

Description

Parameters

Responses

Consumes

Produces

Example HTTP request

Request

Request body

Example HTTP response

Response 200

Add Players to Team

Description

Parameters

Responses

Consumes

Produces

Example HTTP request

Request

Request body

Example HTTP response

Response 200

Remove Players from Team

Description

Parameters

Responses

Consumes

Produces

Example HTTP request

Request

Request body

Example HTTP response

Response 200

Add Tournament

Description

Individual Tournament

Team Tournament

Parameters

Responses

Consumes

Produces

Example HTTP request (with participantType INDIVIDUAL)

Request

Example HTTP request (with participantType `INDIVIDUAL`)

Example HTTP response (with participantType `INDIVIDUAL`)

Example HTTP request (for participantType `TEAM`)

Example HTTP response (with participantType `TEAM`)