Build a points leaderboard

​

Overview

The GET /api/loyalty/accounts endpoint enables you to fetch loyalty points balances for your users, which can be used to build features like a leaderboard in your application. With sorting and pagination options, the endpoint allows you to manage large datasets and customize the display order, making it easy to highlight the top users based on their points. Below is an example and detailed instructions for constructing a leaderboard.

​

Steps to Build a Leaderboard

​

Fetching the data

The GET /api/loyalty/accounts endpoint allows for fetching of loyalty points balances for your users. This endpoints provides various filters to allow sorting, pagination and other filters.

• Note: if your loyalty program contains multiple loyalty currencies then use the loyaltyCurrencyId filter to query for the specific currency you wish to target.

​

Sorting & pagination

The GET /api/loyalty/accounts endpoint supports various query parameters that allow you to retrieve and manage data efficiently:

1. Sorting: Use the orderBy filter to sort users by their points. For example, setting orderBy[amount]=desc ensures users with the highest point balances appear at the top of your leaderboard.
2. Pagination:
   • The limit filter determines how many entries are fetched per request. The default value is 10, but it supports up to 1,000 entries per call.
   • If your dataset contains more than the specified limit (e.g., over 1,000 users), the API response will include a hasNextPage boolean property. When this is true, you’ll need to fetch additional pages.
   • To fetch the next set of data, take the id of the last entry in your previous result and pass it to the startingAfter query filter in your next request.

​

Example Request

Request

{
  "organizationId": "your-organization-id",
  "websiteId": "your-website-id",
  "loyaltyCurrencyId": "your-loyalty-currency-id",
  "orderBy[amount]": "desc",
  "limit": 1000
}

• Note: for paginated requests be sure to add the startingAfter property to subsequent requests.

​

Example Response

{
  "data": [
    {
      "id": "0abcd123-abcd-1234-5678-abcd12345678",
      "userId": "01234abc-abcd-1234-5678-abcd12345678",
      "loyaltyCurrencyId": "your-loyalty-currency-id",
      "amount": "1500",
      "lockVersion": "10",
      "organizationId": "your-organization-id",
      "websiteId": "your-website-id",
      "createdAt": "2024-11-26T17:21:29.688Z",
      "updatedAt": "2024-11-27T17:44:35.881Z",
      "user": {
        "id": "01234abc-abcd-1234-5678-abcd12345678",
        "walletAddress": "0x1...abc",
        "userMetadata": [
          {
            "walletGroupIdentifier": null,
            "twitterUser": "user1",
            "discordUser": "user1",
            "logoUrl": "https://...png",
            "displayName": "user1"
          }
        ]
      }
    },
    {
      "id": "abcd1234-abcd-1234-5678-abcd12345678",
      "userId": "abcd1234-abcd-1234-5678-abcd12345678",
      "loyaltyCurrencyId": "your-loyalty-currency-id",
      "amount": "1250",
      "lockVersion": "10",
      "organizationId": "your-organization-id",
      "websiteId": "your-website-id",
      "createdAt": "2024-11-26T17:21:29.688Z",
      "updatedAt": "2024-11-27T17:44:35.881Z",
      "user": {
        "id": "abcd1234-abcd-1234-5678-abcd12345678",
        "walletAddress": "0x2...abc",
        "userMetadata": [
          {
            "walletGroupIdentifier": null,
            "twitterUser": "user2",
            "discordUser": "user2",
            "logoUrl": "https://...png",
            "displayName": "user2"
          }
        ]
      }
    }],
    "hasNextPage": "false"
}

​

Example Usage

With the above data, you can construct a leaderboard that highlights your top users. The amount field provides the points total, while the userMetadata object contains user details like their display name, social media profiles, and profile picture. Displaying these details can make the leaderboard more engaging and personalized.

​

Summary

By leveraging the /api/loyalty/accounts endpoint, you can create a dynamic points leaderboard for your application. Sorting and pagination options ensure scalability, even with large datasets, while additional user metadata allows you to create a rich and engaging user experience.