Update an existing leaderboard

What this endpoint does

Reads, updates, or deletes one leaderboard by id, depending on the HTTP method on this page (GET, PATCH, or DELETE).

INFO

Prove list first

A key that cannot list leaderboards should not get, patch, or delete them. Add leaderboard, call GET /v1/leaderboards, then use an id from that list.

Quick start

Replace the method with PATCH or DELETE only after a disposable board exists. Do not patch prize/reset on a live community from docs.

Authentication and permission

Bearer community API key. Required permission: leaderboard.

Complete examples

Permission missing (403). Same AUTH_PERMISSION_REQUIRED body as the list page when leaderboard is missing.

GET success (200). message is Read leaderboard success. data is one board object with the same fields as a list row (_id, name, slug, rankBy, displayedFields, widget, and the rest).

{
  "meta": { "status": "success", "statusCode": 200 },
  "message": "Read leaderboard success.",
  "data": {
    "_id": "<leaderboardID>",
    "name": "Example board",
    "slug": "example-board",
    "rankBy": "Messages Sent"
  }
}

PATCH and DELETE success bodies were not captured in this pass. Do not invent them.

Success and readback

GET 200 is the readback for PATCH. After DELETE, the id should disappear from the list.

Errors and recovery

Status	When	Recovery
`403` `leaderboard`	Key lacks permission	Grant `leaderboard`.
`404`	Path without `/v1`	Prefix `/v1`.
`401`	Missing or invalid token	Replace the key.

Retry safety

WARNING

Exact retry

GET is safe to retry. PATCH/DELETE are mutations. Do not retry timeouts without reading the item or list first.

Gotchas

{leaderboardID} is not a user id.

Widget configuration on a board is not the public widget iframe guide.

Next steps

List leaderboards

Get a real id only after list returns 200.

curl --location --request PATCH 'https://adss-production.returning.ai/apis/partner/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 }'

{ "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" } }

Update an existing leaderboard

What this endpoint does

Quick start

Authentication and permission

Complete examples

Success and readback

Errors and recovery

Retry safety

Gotchas

Next steps

Request

Responses

Update an existing leaderboard

What this endpoint does#

Quick start#

Authentication and permission#

Complete examples#

Success and readback#

Errors and recovery#

Retry safety#

Gotchas#

Next steps#

Request

Responses

What this endpoint does

Quick start

Authentication and permission

Complete examples

Success and readback

Errors and recovery

Retry safety

Gotchas

Next steps