Create a new leaderboard - Returning.AI-dev

Creates a leaderboard for the API-key community and returns the created leaderboard document.

Use this when a partner integration needs to create a custom leaderboard using the current micro-services leaderboard schema, including rank permissions, viewing permissions, widget, prize, reset, banner, translations, and page configuration fields.

Authentication:

Bearer API key in Authorization header

Required permission: leaderboard

Community is resolved from the API key token; do not pass communityID

Returns 401 if missing, invalid, or insufficient

Side effects:

Creates a leaderboard in the resolved community

Publishes the create:leaderboard command through the partner publisher path

Gamification service processes the command and persists the leaderboard

New leaderboard appears in the custom leaderboard UI after persistence

Rate limits:

Standard API rate limits apply

Constraints:

name must be 1-100 characters

slug must be unique per community and match lowercase letters, numbers, and hyphens

Create requires rank permissions: provide at least one non-empty users, roles, or tags array through rankedUserRoles or the flat allowedUsersToRank / allowedRolesToRank / allowedTagsToRank fields

Create requires viewing permissions: provide at least one non-empty users, roles, or tags array through viewPermissionUserRoles or the flat allowedUsersToView / allowedRolesToView / allowedTagsToView fields

Missing or empty rank permissions return 400 with Ranked user roles are required

Missing or empty viewing permissions return 400 with View permission user roles are required

Duplicate leaderboard names return 409 with Custom leaderboard name is already exists!

Duplicate leaderboard slugs return 409 with Leaderboard slug already exists: <slug>

Current micro-services fields are accepted: leaderImage, rankBy, displayedFields, displayFieldsOrder, duration, rankedUserRoles, viewPermissionUserRoles, widget, banner, translations, enableLeaderboardReset, leaderboardResetFrequency, enablePrizePool, prizes, userInformationDisplay, leaderboardPageConfig, enabled, previewEnabled, and order

Partner aliases are also accepted: image, rankingField, displayedColumns, startDate, endDate, hasNoEndDate, allowedUsersToRank, allowedRolesToRank, allowedTagsToRank, allowedUsersToView, allowedRolesToView, allowedTagsToView, isEnabled, isPreviewEnabled, and displayOrder

When both alias and micro-services fields are present, alias source-of-truth fields win for image, rankBy, display fields, duration, rank permissions, viewing permissions, enabled, preview, and order mapping as implemented by the partner adapter

duration.start and flat startDate accept ISO date-time and legacy DD-MM-YYYY; duration.end and endDate may be null

enableLeaderboardReset: true requires leaderboardResetFrequency

order: 0 or omitted appends the leaderboard; positive values insert at that position and shift existing entries

widget.size accepts dynamic, fixed, or the legacy object shape { type, value: { width, height } }

Example — create full canonical payload:

{
  "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": "กระดานผู้นำเดือนเมษายน" }
    ],
    "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
}

Related endpoints:

GET /leaderboards — list leaderboards

GET /leaderboards/{leaderboardID} — read a single leaderboard

PATCH /leaderboards/{leaderboardID} — update a leaderboard

DELETE /leaderboards/{leaderboardID} — delete a leaderboard

Responses

🟢201Created

application/json

Leaderboard created successfully. Envelope fields are required; leaderboard data fields are optional because response projection and legacy rows can omit fields.

Bodyapplication/json

🟠400Bad Request

🟠401Unauthorized

🟠409Forbidden

🔴500Server Error

🔴502Bad Gateway

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

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