Skip to content

LeaderBoardsController API Documentation

Jump to bottom
Lee Sambridge edited this page Jul 14, 2025 · 3 revisions

LeaderBoards API Documentation

This document provides documentation for the LeaderBoards API endpoints available in the Points.Api system.

Table of Contents

Authentication

All endpoints in the LeaderBoards API require JWT Bearer authentication. Include the JWT token in the Authorization header of your requests:

Authorization: Bearer {your_jwt_token}

Model Definitions

CreateUserLeaderboardRequest

The CreateUserLeaderboardRequest model represents a request to create a new user leaderboard with the following fields:

Field Type Description
name string Name of the user leaderboard
activityIds List List of activity IDs associated with the leaderboard
daysToRun long Number of days the leaderboard will run (default: 0)
startTime DateTime Start time of the leaderboard (default: current UTC time)

Endpoints

Add Emails to LeaderBoard

Adds a list of email addresses to a user's leaderboard.

URL: /api/LeaderBoards/partner/{partnerId}/user/{userId}/UserleaderBoard/{boardId}

Method: PUT

Auth required: Yes (JWT Bearer token)

URL Parameters:

  • partnerId (long) - ID of the partner
  • userId (long) - ID of the user
  • boardId (long) - ID of the leaderboard

Request Body:

[
  "email1@example.com",
  "email2@example.com"
]

Success Response:

  • Code: 200 OK
  • Content: Result of the operation

Add or Edit LeaderBoards

Creates a new leaderboard or updates an existing one.

URL: /api/LeaderBoards/{partnerId}

Method: POST

Auth required: Yes (JWT Bearer token)

URL Parameters:

  • partnerId (long) - ID of the partner

Request Body:

{
  "id": 0,
  "name": "My Leaderboard",
  "description": "Leaderboard description",
  "startDate": "2025-03-21T00:00:00Z",
  "endDate": "2025-04-21T00:00:00Z",
  "isActive": true
}

Success Response:

  • Code: 200 OK
  • Content: Created or updated leaderboard

Add User to the LeaderBoard

Adds a user to an existing leaderboard.

URL: /api/LeaderBoards/{partnerId}/board/{boardId}/user/{userId}

Method: POST

Auth required: Yes (JWT Bearer token)

URL Parameters:

  • partnerId (long) - ID of the partner
  • boardId (long) - ID of the leaderboard
  • userId (long) - ID of the user to add

Success Response:

  • Code: 200 OK
  • Content: Result of the operation

Add Users to the LeaderBoard

Adds multiple users to an existing leaderboard in a single request.

URL: /api/LeaderBoards/{partnerId}/board/{boardId}/users

Method: POST

Auth required: Yes (JWT Bearer token)

URL Parameters:

  • partnerId (long) - ID of the partner
  • boardId (long) - ID of the leaderboard

Request Body:

[
  123,
  456,
  789
]

Array of user IDs to add to the leaderboard.

Success Response:

  • Code: 200 OK
  • Content:
{
  "usersAdded": 3,
  "leaderBoardId": 456
}

Add User to the Streak

Adds a user to an activity streak.

URL: /api/LeaderBoards/{partnerId}/streak/{streakId}/user/{userId}

Method: POST

Auth required: Yes (JWT Bearer token)

URL Parameters:

  • partnerId (long) - ID of the partner
  • streakId (long) - ID of the streak
  • userId (long) - ID of the user to add

Success Response:

  • Code: 200 OK
  • Content: Result of the operation

Check Email Address

Checks if an email address is registered with a partner.

URL: /api/LeaderBoards/{partnerId}/email/{email}

Method: GET

Auth required: Yes (JWT Bearer token)

URL Parameters:

  • partnerId (long) - ID of the partner
  • email (string) - Email address to check

Success Response:

  • Code: 200 OK
  • Content: Boolean indicating if the email is registered

Create New User LeaderBoard

Creates a new user-specific leaderboard.

URL: /api/LeaderBoards/partner/{partnerId}/user/{userId}/UserleaderBoard

Method: POST

Auth required: Yes (JWT Bearer token)

URL Parameters:

  • partnerId (long) - ID of the partner
  • userId (long) - ID of the user

Request Body:

{
  "name": "My User Leaderboard",
  "activityIds": ["1", "2", "3"],
  "daysToRun": 30,
  "startTime": "2025-07-14T00:00:00Z"
}

Success Response:

  • Code: 200 OK
  • Content: Created user leaderboard

Example Response:

{
  "id": 123,
  "name": "My User Leaderboard",
  "activityIds": ["1", "2", "3"],
  "daysToRun": 30,
  "startTime": "2025-07-14T00:00:00Z",
  "endTime": "2025-08-13T00:00:00Z"
}

Success Response:

  • Code: 200 OK
  • Content: Created user leaderboard

Delete LeaderBoard

Deletes a leaderboard.

URL: /api/LeaderBoards/{partnerId}/board/{boardId}

Method: DELETE

Auth required: Yes (JWT Bearer token)

URL Parameters:

  • partnerId (long) - ID of the partner
  • boardId (long) - ID of the leaderboard to delete

Success Response:

  • Code: 200 OK
  • Content: Result of the operation

Get Current LeaderBoard

Retrieves the current state of a leaderboard.

URL: /api/LeaderBoards/{partnerId}/current/{leaderboardId}

Method: GET

Auth required: Yes (JWT Bearer token)

URL Parameters:

  • partnerId (long) - ID of the partner
  • leaderboardId (long) - ID of the leaderboard

Success Response:

  • Code: 200 OK
  • Content: Current leaderboard data

Get LeaderBoard Counts

Retrieves the count of users in a leaderboard.

URL: /api/LeaderBoards/{partnerId}/board/{boardId}/count

Method: GET

Auth required: Yes (JWT Bearer token)

URL Parameters:

  • partnerId (long) - ID of the partner
  • boardId (long) - ID of the leaderboard

Success Response:

  • Code: 200 OK
  • Content: Count of users in the leaderboard

Get LeaderBoard History

Retrieves the history of a leaderboard.

URL: /api/LeaderBoards/{partnerId}/history/{leaderboardId}

Method: GET

Auth required: Yes (JWT Bearer token)

URL Parameters:

  • partnerId (long) - ID of the partner
  • leaderboardId (long) - ID of the leaderboard

Success Response:

  • Code: 200 OK
  • Content: Historical leaderboard data

Get LeaderBoard History by Run

Retrieves a specific run of a leaderboard's history.

URL: /api/LeaderBoards/{partnerId}/history/{leaderboardId}/run/{run}

Method: GET

Auth required: Yes (JWT Bearer token)

URL Parameters:

  • partnerId (long) - ID of the partner
  • leaderboardId (long) - ID of the leaderboard
  • run (int) - Run number to retrieve

Success Response:

  • Code: 200 OK
  • Content: Historical leaderboard data for the specified run

Get LeaderBoards

Retrieves all leaderboards for a partner.

URL: /api/LeaderBoards/{partnerId}

Method: GET

Auth required: Yes (JWT Bearer token)

URL Parameters:

  • partnerId (long) - ID of the partner

Success Response:

  • Code: 200 OK
  • Content: List of leaderboards

Get LeaderBoards by Active Status

Retrieves leaderboards for a partner filtered by active status.

URL: /api/LeaderBoards/{partnerId}/active/{active}

Method: GET

Auth required: Yes (JWT Bearer token)

URL Parameters:

  • partnerId (long) - ID of the partner
  • active (boolean) - Active status filter

Success Response:

  • Code: 200 OK
  • Content: List of filtered leaderboards

Get LeaderBoards for User

Retrieves leaderboards for a specific user.

URL: /api/LeaderBoards/{partnerId}/users/{userId}

Method: GET

Auth required: Yes (JWT Bearer token)

URL Parameters:

  • partnerId (long) - ID of the partner
  • userId (long) - ID of the user

Query Parameters:

  • totalToShow (int) - Number of leaderboards to return

Success Response:

  • Code: 200 OK
  • Content: List of user's leaderboards

Get LeaderBoards for User (Active)

Retrieves active leaderboards for a specific user.

URL: /api/LeaderBoards/{partnerId}/users/{userId}/active

Method: GET

Auth required: Yes (JWT Bearer token)

URL Parameters:

  • partnerId (long) - ID of the partner
  • userId (long) - ID of the user

Query Parameters:

  • totalToShow (int) - Number of leaderboards to return

Success Response:

  • Code: 200 OK
  • Content: List of user's active leaderboards

Get LeaderBoards for User (Past)

Retrieves past leaderboards for a specific user.

URL: /api/LeaderBoards/{partnerId}/users/{userId}/past

Method: GET

Auth required: Yes (JWT Bearer token)

URL Parameters:

  • partnerId (long) - ID of the partner
  • userId (long) - ID of the user

Query Parameters:

  • totalToShow (int) - Number of leaderboards to return

Success Response:

  • Code: 200 OK
  • Content: List of user's past leaderboards

Get LeaderBoards Information

Retrieves detailed information about all leaderboards for a partner.

URL: /api/LeaderBoards/{partnerId}/UserleaderboardDetails

Method: GET

Auth required: Yes (JWT Bearer token)

URL Parameters:

  • partnerId (long) - ID of the partner

Success Response:

  • Code: 200 OK
  • Content: Detailed leaderboard information

Get Live LeaderBoards

Retrieves live leaderboards for a user.

URL: /api/LeaderBoards/{partnerId}/live/user/{userId}

Method: GET

Auth required: Yes (JWT Bearer token)

URL Parameters:

  • partnerId (long) - ID of the partner
  • userId (long) - ID of the user

Success Response:

  • Code: 200 OK
  • Content: List of live leaderboards

Get Partner Activity Streak

Retrieves a specific activity streak for a partner.

URL: /api/LeaderBoards/{partnerId}/streak/{streakId}

Method: GET

Auth required: Yes (JWT Bearer token)

URL Parameters:

  • partnerId (long) - ID of the partner
  • streakId (long) - ID of the streak

Success Response:

  • Code: 200 OK
  • Content: Activity streak details

Get Partner Activity Streaks

Retrieves all activity streaks for a partner.

URL: /api/LeaderBoards/{partnerId}/streak/

Method: GET

Auth required: Yes (JWT Bearer token)

URL Parameters:

  • partnerId (long) - ID of the partner

Success Response:

  • Code: 200 OK
  • Content: List of activity streaks

Get User LeaderBoard Invites

Retrieves invites for a user's leaderboard.

URL: /api/LeaderBoards/{partnerId}/Userleaderboards/user/{userId}/board/{boardId}/Invites

Method: GET

Auth required: Yes (JWT Bearer token)

URL Parameters:

  • partnerId (long) - ID of the partner
  • userId (long) - ID of the user
  • boardId (long) - ID of the leaderboard

Success Response:

  • Code: 200 OK
  • Content: List of leaderboard invites

Get User LeaderBoards

Retrieves all leaderboards created by a user.

URL: /api/LeaderBoards/{partnerId}/Userleaderboards/user/{userId}

Method: GET

Auth required: Yes (JWT Bearer token)

URL Parameters:

  • partnerId (long) - ID of the partner
  • userId (long) - ID of the user

Success Response:

  • Code: 200 OK
  • Content: List of user-created leaderboards

Remove User from the LeaderBoard

Removes a user from a leaderboard.

URL: /api/LeaderBoards/{partnerId}/board/{boardId}/user/{userId}

Method: DELETE

Auth required: Yes (JWT Bearer token)

URL Parameters:

  • partnerId (long) - ID of the partner
  • boardId (long) - ID of the leaderboard
  • userId (long) - ID of the user to remove

Success Response:

  • Code: 200 OK
  • Content: Result of the operation

Remove User from the Streak

Removes a user from an activity streak.

URL: /api/LeaderBoards/{partnerId}/streak/{streakId}/user/{userId}

Method: DELETE

Auth required: Yes (JWT Bearer token)

URL Parameters:

  • partnerId (long) - ID of the partner
  • streakId (long) - ID of the streak
  • userId (long) - ID of the user to remove

Success Response:

  • Code: 200 OK
  • Content: Result of the operation

Resend Invite Email

Resends an invitation email for a leaderboard.

URL: /api/LeaderBoards/Userleaderboards/Invite/{id}

Method: PUT

Auth required: Yes (JWT Bearer token)

URL Parameters:

  • id (long) - ID of the invitation

Success Response:

  • Code: 200 OK
  • Content: Result of the operation

Terms and Conditions | Privacy Policy | Acceptable Use Policy | Cookie Policy

Clone this wiki locally