List General Points Leaderboard Entries

Server URLloading...

POST

/api/v1/external/gamification/leaderboards/points

Send

Authorization

Header

Body

Returns the authenticated creator's ranked subscribers for general points. Use this operation to render or synchronize a leaderboard; use getPointsLedgerByUser for one user's activity history or getCollectivePointsByUser for one user's aggregate points.

An empty body selects the lifetime period, page 1, 25 entries, and no badge, Mango, or point-range filters. Eligible users have an active or manually active, unexpired subscription to at least one Mango enabled for gamification on this host. Pages are ordered by rank ascending, then user ID descending. Equal point totals share the same rank. A page beyond the final page returns an empty data array while total still reports all matches.

Filter rules:

• Include arrays match users with any listed value; exclude arrays remove users with any listed value. Each array must be non-empty when present, include and exclude arrays must be disjoint, and there is no application-level item-count limit.
• An exclude-only badge filter considers users who have at least one badge from this creator; users with no creator badges are not included. Badge IDs must belong to this creator.
• Mango IDs must be enabled for gamification on this host. Point bounds are inclusive and must be supplied together. Point, badge, and Mango filter groups are combined with AND.

This POST performs a read and is safe to retry. If the cached ranks are stale or missing, the request refreshes ranks before loading the page; repeated requests inside the configured refresh interval skip that refresh. Refresh metadata is captured before this check, so a stale request can return refreshed rows with the previous lastUpdatedAt and nextRefreshAt; the next request reports the new refresh window.

Malformed ObjectIds, literal nulls, empty filter arrays, and scalar constraint violations return the standard validation 400 response. Cross-field request failures use LEADERBOARD_INVALID_REQUEST.

Header Parameters

Response Body

curl -X POST "https://api-prod-new.tagmango.com/api/v1/external/gamification/leaderboards/points" \  -H "x-whitelabel-host: string" \  -H "Content-Type: application/json" \  -d '{}'

{
  "data": [
    {
      "rank": 26,
      "points": 740,
      "user": {
        "_id": "6659ca9e5f2acb7abfdcd8fd",
        "name": "John Doe",
        "email": "john.doe@example.com",
        "phone": 1234567890,
        "profilePicUrl": "https://linktoprofilepic.com/pic.jpg",
        "country": "India"
      },
      "mangoes": [
        {
          "_id": "66a1390268a76f2f5c9f39a3",
          "title": "Introduction to Coding"
        }
      ],
      "badges": [
        {
          "_id": "6659ca9e5f2acb7abfdcd8fd",
          "name": "Hall Of Fame",
          "imageUrl": "https://testing.tagmango.com/assets/badge-icon-922e7f499bc0045d7af8ac771eebe2fe.png"
        }
      ]
    }
  ],
  "total": 27,
  "lastUpdatedAt": "2026-08-24T04:26:54.806Z",
  "nextRefreshAt": "2026-08-24T05:26:54.806Z",
  "refreshIntervalSeconds": 3600
}

{
  "code": 400,
  "type": "Bad Request",
  "statusMessage": "BAD_REQUEST",
  "errorCode": "LEADERBOARD_INVALID_REQUEST",
  "message": "Check the leaderboard request body. Provide pointMin and pointMax together, keep pointMin less than or equal to pointMax, and do not place the same ID in both include and exclude filters.",
  "result": "Check the leaderboard request body. Provide pointMin and pointMax together, keep pointMin less than or equal to pointMax, and do not place the same ID in both include and exclude filters.",
  "success": false
}

{
  "code": 401,
  "type": "Unauthorized",
  "statusMessage": "UNAUTHORIZED",
  "message": "Invalid token",
  "result": "Invalid token",
  "success": false
}

{
  "code": 403,
  "type": "Forbidden",
  "statusMessage": "FORBIDDEN",
  "errorCode": "WORKSHOP_MANGO_FORBIDDEN",
  "message": "You can not access this api with a TagMango account, only available for whitelabel hosts",
  "result": "You can not access this api with a TagMango account, only available for whitelabel hosts",
  "success": false
}

{
  "code": 404,
  "type": "Not Found",
  "statusMessage": "NOT_FOUND",
  "errorCode": "LEADERBOARD_HOST_NOT_FOUND",
  "message": "We could not find a points leaderboard for the authenticated creator and host.",
  "result": "We could not find a points leaderboard for the authenticated creator and host.",
  "success": false
}

{
  "code": 429,
  "type": "Too Many Requests",
  "statusMessage": "TOO_MANY_REQUESTS",
  "message": "Request limit exceeded. try after 10 seconds",
  "result": "Request limit exceeded. try after 10 seconds",
  "success": false
}

{
  "code": 500,
  "type": "UnknownError",
  "statusMessage": "INTERNAL_SERVER_ERROR",
  "errorCode": "LEADERBOARD_REFRESH_FAILED",
  "message": "We could not refresh the points leaderboard ranks. Please try again later.",
  "result": "We could not refresh the points leaderboard ranks. Please try again later.",
  "success": false
}