Send score

Description

Every time a user finishes a game or similar, use this endpoint to send the user's score. GameRank maintains the user's personal best, the leaderboard podium, etc.

Endpoint

POST https://api.gamerank.io/leaderboard/score

Request JSON body

Field	Type	Optional	Description
score	int		User's score
username	string		Displayable user's name
userid	string	Yes	User's unique identifier. Alpha-numerical ASCII characters only. If not provided: a random id is generated.
return_best	bool	Yes	If set to true, the response will contain the player's current best score and current best position in the leaderboard.

Example

{
    "score": 3340,
    "username": "John Doe",
    "userid": "1289",
    "return_best": false
}

Response JSON body

Field	Type	Description
userid	string	User id used to store this score.
best_position	int	Best position of the user in the leaderboard. Only present if return_best is set to true in the request.
best_score	int	User's best score in the leaderboard. Only present if return_best is set to true in the request.
best_score_creation_time	millisecond timestamp	UTC timestamp in millisecond at which the player did their best score. Only present if return_best is set to true in the request.
is_new_best	bool	true if the score just sent is the new personal best of the user. Only present if return_best is set to true in the request.

{
    "userid": "1289",

    // Following fields are only present if `return_best` is set
    // to `true` in the request.

    "best_position": 43,
    "best_score": 328716,
    "best_score_creation_time": 1730026754899,
    "is_new_best": false
}

HTTP status code

HTTP status	Reason(s)
200	• OK, score processed
400	• Malformed JSON • Empty username • Invalid user ID format
404	• Unknown API key / leaderboard
500	• Server Error, please contact support@gamerank.io