Update an existing leaderboard
PATCH
/leaderboards/{leaderboardID}
leaderImage, order, banner, translations, reset/prize settings, user display settings, page config, and the expanded widget configuration are accepted. Legacy partner aliases are still accepted where supported by the service adapter. Send only fields that should change.Request
Path Params
Header Params
Body Params application/jsonRequired
Responses
Request Request Example
Shell
JavaScript
Java
Swift
curl --location --request PATCH 'https://adss-integration.returning.ai/apis/leaderboards/65f1b2c3d4e5f67890123456' \
--header 'Authorization: Bearer XXXXXX' \
--header 'Content-Type: application/json' \
--data '{
"leaderImage": "https://cdn.example.com/leaderboards/april.png",
"name": "April Updated Leaderboard",
"slug": "april-updated-leaderboard",
"description": "Monthly leaderboard updated 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": 2
}'Response Response Example
{
"meta": {
"status": "success",
"statusCode": 200
},
"message": "Update leaderboard success.",
"data": {
"_id": "507f1f77bcf86cd799439012",
"communityID": "6502c97314a3e564c5bbfa84",
"name": "April Updated Leaderboard",
"slug": "april-updated-leaderboard",
"description": "Monthly leaderboard updated 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": "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,
"displayOrder": 2,
"order": 2,
"selected": false,
"createdAt": "2026-05-20T10:00:00.000Z",
"updatedAt": "2026-05-20T10:00:00.000Z"
}
}Modified at 2026-06-11 10:14:56