Create a new leaderboard
POST
/leaderboards
What this endpoint does
INFO
leaderboard, prove GET /v1/leaderboards returns 200, then create a throwaway board in tests.Quick start
name is not the full required body. If you POST /leaderboards without /v1, expect a missing route.Authentication and permission
leaderboard. Community comes from the token; do not pass communityID.leaderboard receives 403 AUTH_PERMISSION_REQUIRED on the sibling list.Complete examples
AUTH_PERMISSION_REQUIRED body as list leaderboards.Success and readback
GET /v1/leaderboards and GET /v1/leaderboards/{leaderboardID}.Errors and recovery
| Status | When | Recovery |
|---|---|---|
403 AUTH_PERMISSION_REQUIRED leaderboard | Key lacks permission | Add leaderboard. Do not keep POSTing. |
404 | Path without /v1 | Use /v1/leaderboards. |
401 | Missing or invalid Bearer token | Add a valid community key. |
Retry safety
WARNING
Gotchas
/v1/leaderboards/{leaderboardID} and the same permission.Next steps
Request
Header Params
Body Params application/jsonRequired
Responses
Request Request Example
Shell
JavaScript
Java
Swift
curl --location 'https://adss-production.returning.ai/apis/partner/leaderboards' \
--header 'Authorization: Bearer XXXXXX' \
--header 'Content-Type: application/json' \
--data '{
"leaderImage": "https://cdn.example.com/leaderboards/april.png",
"name": "April Last Leaderboard",
"slug": "april-last-leaderboard",
"description": "Monthly leaderboard created through the partner API.",
"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": "30-01-2026",
"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,
"order": 0
}'Response Response Example
201 - Success Example
{
"meta": {
"status": "success",
"statusCode": 201
},
"message": "Create 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-08-19 03:30:29