Download Manual Download

Navigation Mobile menu

List Players

Overview

This end point allows you to retrieve expanded player objects for your game. As the only way to query this end point is with a secret key, this should only be called by back end services.

You can specify a list of player ID's to specify explicitly, otherwise all the players in your game will be returned.

Request URL

All parameters in the request must be sent as a POST HTTP request. Make all requests to the following URL:

https://auth.construct.net/listplayers.json

Authenticating The Request

This end point is for secret key authenticated requests only. Signed in players cannot call this end point.

secret string Required: Your games secret API key.

Request Parameters

gameID guid Required: The ID of the game you are making this request against. You can find the ID of your game in your Construct Game Services (CGS) account.
order string: How you wish the players returned in this query to be ordered. Can be one of None, AZ, ZA, Newest, Oldest or MostRecentlyActive. The default value if not specified is Newest.
playerIDs string: A comma separated list of player ID's you explicitly wish to fetch. This list cannot contain more than 300 player ID's.
perPage int32: How many players you wish to return on each page of results. Cannot be less than 1 or more than 200. Default value is 50.
page int32: The page of results you are requesting. The first page is always 1. If this value is not specified the first page will be returned.
culture string Optional: Optionally specify a supported culture code for rendering various properties. If not specified, the culture code from your games default language will be used.

Success Response

Successful responses always return a HTTP 200 status code.

{
  "success": true,
  "pagination": { ... },
  "players": [
    { ... },
    { ... }
  ],
  "formattingCulture": "en-us"
}

Response Properties

success bool: If the request was successfull or not.
pagination Pagination: If there are more players returned than can be shown in one page of results, the pagination object can help you browse through the other pages of results.
players Array<ExpandedPlayer>: The players returned on this page of results for the query.
formattingCulture string: If some return values are culture specific, this property indicates what culture the values have been rendered as.

Failure Response

Unsuccessful responses always return HTTP 4xx status codes.

{
  "success": false,
  "errorMessage": "Your request failed due to...",
  "helpURL": "https://www.construct.net/en/game-services/manuals/game-services/authentication/api-end-points/players/list-players",
  "shouldRetry": false
}

Response Properties

success bool: If the request was successfull or not.
errorMessage string: An error message with more detailed information on why the request failed.
helpURL url (string): A link to documentation which should provide help with the error.
shouldRetry bool: Should the client wait a short period of time and retry the request. Usually this is false, but returns true if the request failed due to rate limiting.