Get a single leaderboard by ID

GET

/leaderboards/{leaderboardID}

Returns one leaderboard for the community resolved from the bearer API key. The response mirrors the current micro-services leaderboard schema, including leaderImage, reset/prize settings, banner, translations, user display settings, page config, and expanded widget configuration.

Request

Path Params

Query Params

Header Params

Responses

🟢200OK

application/json

Leaderboard returned successfully.

Bodyapplication/json

🟠400Bad Request

🟠401Unauthorized

🟠404Record Not Found

🔴500Server Error

🔴502Bad Gateway

Request Example

Shell

JavaScript

Java

Swift

curl --location 'https://api.returning.ai/v1/leaderboards/65f1b2c3d4e5f67890123456?fields=name%2Cslug%2CleaderImage%2Cwidget%2CenablePrizePool' \
--header 'Authorization: Bearer XXXXXX'

Response Example

{
    "meta": {
        "status": "success",
        "statusCode": 200
    },
    "message": "Read leaderboard success.",
    "data": {
        "_id": "507f1f77bcf86cd799439012",
        "communityID": "6502c97314a3e564c5bbfa84",
        "name": "April Last Leaderboard",
        "slug": "april-last-leaderboard",
        "description": "Monthly leaderboard created through the partner API.",
        "image": "https://cdn.example.com/leaderboards/april.png",
        "rankBy": "currencies",
        "displayedFields": [
            "user",
            "currencies",
            "xps",
            "level"
        ],
        "displayFieldsOrder": [
            "user",
            "currencies",
            "xps",
            "level"
        ],
        "timeFilters": [
            "all-time",
            "daily",
            "weekly",
            "monthly",
            "yearly"
        ],
        "performanceDisplay": {
            "showTop": {
                "enabled": true,
                "value": 10
            },
            "showPositive": {
                "enabled": true
            },
            "showDummy": {
                "enabled": false
            }
        },
        "duration": {
            "start": "2026-01-30T00:00:00.000Z",
            "end": null,
            "noEndDate": true,
            "timeZone": 7,
            "startTime": {
                "hours": 12,
                "minutes": 0,
                "ampm": "AM"
            },
            "endTime": {
                "hours": 11,
                "minutes": 59,
                "ampm": "PM"
            }
        },
        "rankedUserRoles": {
            "users": [],
            "roles": [
                "6502c97314a3e564c5bbfa84"
            ],
            "tags": []
        },
        "viewPermissionUserRoles": {
            "users": [],
            "roles": [
                "6502c97314a3e564c5bbfa84"
            ],
            "tags": []
        },
        "widget": {
            "enabled": true,
            "apiKey": "widget-key",
            "whitelistedDomains": [
                "example.com"
            ],
            "size": "dynamic",
            "width": null,
            "height": null,
            "theme": {
                "default": "dark",
                "dark": {
                    "name": "Custom Dark",
                    "accent": "#7C3AED",
                    "accent2": "#22C55E",
                    "accent3": "#F59E0B",
                    "accent4": "#EF4444",
                    "text": "#FFFFFF",
                    "text2": "#E5E7EB",
                    "text3": "#D1D5DB",
                    "text4": "#9CA3AF",
                    "text5": "#6B7280",
                    "text6": "#4B5563",
                    "background": "#111827",
                    "background2": "#1F2937",
                    "background3": "#374151",
                    "background4": "#4B5563",
                    "background5": "#6B7280",
                    "background6": "#9CA3AF",
                    "background7": "#D1D5DB",
                    "divider": "#374151",
                    "divider2": "#4B5563",
                    "shadow": "#000000",
                    "scrollbarBackground": "#1F2937",
                    "scrollbarThumb": "#6B7280"
                }
            },
            "font": "Inter",
            "ctaButton": {
                "enabled": true,
                "text": "Join",
                "link": "https://example.com/join"
            },
            "button": {
                "enabled": true,
                "text": "View leaderboard",
                "link": "https://example.com/leaderboard"
            },
            "domains": [
                "example.com"
            ],
            "communityThemeOverride": true
        },
        "banner": {
            "enabled": true,
            "title": "April Challenge",
            "description": "Compete for the top monthly prize.",
            "image": "https://cdn.example.com/banners/april.png"
        },
        "translations": {
            "name": [
                {
                    "languageCode": "en",
                    "translation": "April Last Leaderboard"
                },
                {
                    "languageCode": "th",
                    "translation": "April Leaderboard TH"
                }
            ],
            "description": [
                {
                    "languageCode": "en",
                    "translation": "Monthly leaderboard created through the partner API."
                }
            ]
        },
        "enableLeaderboardReset": true,
        "leaderboardResetFrequency": "weekly",
        "enablePrizePool": true,
        "prizes": [
            {
                "_id": "prize-1",
                "position": 1,
                "positionFrom": null,
                "positionTo": null,
                "isRange": false,
                "prizeName": "Champion Reward",
                "useRewardAsPrizeName": false,
                "coins": 1000,
                "xp": 500,
                "customFields": [
                    {
                        "id": "wallet-address",
                        "fieldType": "text",
                        "fieldName": "Wallet Address",
                        "description": "Wallet address used for prize delivery.",
                        "placeholderText": "0x...",
                        "isRequired": true,
                        "isExpanded": false
                    }
                ]
            },
            {
                "_id": "prize-2",
                "position": null,
                "positionFrom": 2,
                "positionTo": 5,
                "isRange": true,
                "prizeName": "Top 5 Reward",
                "useRewardAsPrizeName": false,
                "coins": 500,
                "xp": 250,
                "customFields": []
            }
        ],
        "userInformationDisplay": [
            {
                "field": "name",
                "displayMode": "full",
                "order": 0
            },
            {
                "field": "email",
                "displayMode": "partial",
                "order": 1
            }
        ],
        "leaderboardPageConfig": {
            "bannerDisplay": {
                "enabled": true
            },
            "rolesUsers": {
                "roles": [
                    "6502c97314a3e564c5bbfa84"
                ],
                "users": []
            },
            "viewingPermission": {
                "roles": [
                    "6502c97314a3e564c5bbfa84"
                ],
                "users": []
            },
            "enableWidgets": {
                "enabled": true
            },
            "guestMode": {
                "enabled": false
            },
            "leftPanel": {
                "leaderboardName": true,
                "startAndEndDate": true,
                "countdown": true,
                "eventImage": true,
                "eventDescription": true,
                "prizePool": true
            },
            "rightPanel": {
                "podium": true,
                "userPosition": true,
                "hallOfChampions": true
            },
            "timeFilterView": {
                "allTime": true,
                "daily": true,
                "weekly": true,
                "monthly": true,
                "yearly": false
            }
        },
        "enabled": true,
        "previewEnabled": false,
        "displayOrder": 1,
        "order": 1,
        "selected": false,
        "createdAt": "2026-05-20T10:00:00.000Z",
        "updatedAt": "2026-05-20T10:00:00.000Z"
    }
}

Modified at 2026-06-11 10:14:56

Update an existing leaderboard

Delete a leaderboard