1. Leaderboards
Returning.AI
  • Getting Started
  • Bulk Operations
    • Bulk user updates
    • List bulk update jobs
      GET
    • Get bulk update job status
      GET
    • Get bulk update job details
      GET
    • Bulk update users from CSV
      POST
    • Bulk update premium currency from CSV
      POST
  • Chart Analysis
    • Create Analysis
      POST
    • Get Analysis
      GET
    • Update Analysis
      PATCH
    • Delete Analysis
      DELETE
    • List Analyses
      GET
    • Append Drawings
      POST
  • Rewards & Redemptions
    • Redemption lifecycle
    • Store catalog to redemptions
    • Update redemption order status or refund
    • List redemption orders by user email
    • List redemption statuses
    • Get redemption status by ID
    • List redemption orders by community
    • Create redemption order status
    • Get redemption order status history
    • List redemption orders by custom-field identifier
  • Gamification
    • Leaderboards
      • Leaderboards
      • List leaderboards with pagination
        GET
      • Create a new leaderboard
        POST
      • Update an existing leaderboard
        PATCH
      • Get a single leaderboard by ID
        GET
      • Delete a leaderboard
        DELETE
    • Streaks & Mini Games
      • Mini-game State and History
      • List user streak logs
      • List mini-game logs by user email
      • Get current mini-game and streak state
      • Update user spin-wheel information
    • Referral
      • Referral Program Integration
      • Get referral programs
      • Get user's referral summary
    • Rolling Data
    • Match Predictions
      • Create match prediction
      • List match predictions
      • Get match prediction
      • Patch match prediction
      • Publish match prediction
      • Settle match prediction
      • Get settlement results
      • Void match prediction
      • Bulk update match predictions
      • Get bulk job status
      • Get bulk job results
    • Loyalty Points
      • Create loyalty points export
      • Get loyalty points export status
      • Get loyalty points export download link
    • Quizzes
      • Create quiz
      • List quizzes
      • Get quiz
      • Update quiz
      • Delete quiz
      • Add quiz question
      • Update quiz question
      • Delete quiz question
    • Get tier configuration
      GET
    • Get daily user XP and coin changes
      POST
    • Search user gamification logs
      POST
    • Get user activity stats
      POST
  • Messaging
    • Agent messaging workflow
    • Get Messages
    • Send Message
    • Reply Message
    • React Message
    • Upload message images
  • Users
    • User directory and provisioning
    • Get Users with Filters
    • Create New User
    • Get User Data
    • Manage User Account
    • Get User Milestones
    • Update User Data, Identifier, And Roles
  • Channels
    • Iframe
    • List integration channels
  • Events
    • Outgoing webhooks
      • Encryption
      • User Joins Server
      • User Visits server
      • New Message Posted Anywhere
      • New Message Posted To channel
      • Purchased Store Item
    • Incoming webhooks
      • API Keys & Encryption
      • Send message into channels
      • Update Custom User Fields
      • Update In-game currency
  • Widgets
    • Authenticated Widgets
    • Public widgets
    • Channels
    • Leaderboard
    • Milestone
    • Socials
    • Store
  • Community Analytics
    • Get Loyalty Overview
    • Get Phone Verification Contacts
  • Store
    • Store journey
    • Store catalog
    • Purchase History
      • Archive or restore an order
      • Update redemption instructions or voucher details
    • Categories
      • List Store categories
      • Create Store category
      • Get Store category by ID
      • Update Store category
      • Delete Store category
    • Products
      • List products
      • Create products in bulk
      • Create product with vouchers
      • Update products in bulk
      • Read product
      • Update product and append vouchers
      • Delete product
    • Redemption-transaction
      • Get redemption transaction detail
    • Get Store configuration
    • Update Store configuration
  • Community
    • Community directory and appearance
    • Appearance
      • Update community theme colors
      • Update community bot profile
      • Update community URL metadata
      • Update community name and URL
    • Community Users
      • Get community users
      • Get user
    • Create community
  • User Fields
    • User field definitions and history
    • User Field History
      • List Community User-Field History
      • List One Field Across Users
      • List One User Across Fields
      • List One User's One Field
      • Update A User Field Value
      • Deprecated Field-First History Write
      • Deprecated Field-First History Read
    • Create A User Field Definition
    • Get A User Field Definition
    • Update A User Field Definition
    • Delete A User Field Definition
    • List User Field Definitions
  • API Keys
    • API key lifecycle
    • Community API Keys
      • Create API key
      • Read API keys
      • Delete API key
      • Update API key
    • User API Keys
      • List user API keys
      • Create user API key
      • Update user API key
      • Delete user API key
      • Get current API key information
  • Legacy
    • Servers
      • Create server
      • List servers
      • Update server metadata
    • Bulk Operations
      • Bulk import users from CSV
    • Authentication
      • Register user with password
      • Verify user email
      • Log in user with password
      • Secure Auth
    • Badges
      • List badges
      • Create badge
      • Update badge
      • Delete badge
      • Remove badge from user
      • Award badge to user
    • Messaging
    • Roles & Permissions
      • List server roles
      • Create role
      • Update role
      • Delete role
      • List user roles
      • Add role to user
      • Remove role from user
    • Users
      • Get user
      • Upload user avatar
    • Channels
      • Create channel
      • Update channel
      • Delete channel
    • API Keys
      • List integration API keys
      • Create integration API key
      • Delete integration API key
      • Update integration API key
  • Community Logs
    • Retrieve and export community logs
  1. Leaderboards

Create a new leaderboard

POST
https://sgtr-api.returning.ai/v1/leaderboards
Gamification/Leaderboards

What this endpoint does#

Creates a leaderboard for the community resolved from the Bearer API key.
The request body can include rank permissions, viewing permissions, widget, prize, reset, banner, translations, and page configuration. Copy fields from the schema on this page. Prize and reset fields can affect rewards.
INFO
Prove list first
Grant 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#

Bearer community API key. Required permission: leaderboard. Community comes from the token; do not pass communityID.
A key missing leaderboard receives 403 AUTH_PERMISSION_REQUIRED on the sibling list.

Complete examples#

Permission missing (403). Same AUTH_PERMISSION_REQUIRED body as list leaderboards.
Use the schema on this page for the create body after the list succeeds.

Success and readback#

Read back with GET /v1/leaderboards and GET /v1/leaderboards/{leaderboardID}.

Errors and recovery#

StatusWhenRecovery
403 AUTH_PERMISSION_REQUIRED leaderboardKey lacks permissionAdd leaderboard. Do not keep POSTing.
404Path without /v1Use /v1/leaderboards.
401Missing or invalid Bearer tokenAdd a valid community key.

Retry safety#

WARNING
Exact retry
Create is a mutation. Do not retry timeouts without listing first. Duplicate names may conflict.

Gotchas#

Prize and reset fields can move rewards. Stay on a disposable board in tests.
Get/patch/delete share /v1/leaderboards/{leaderboardID} and the same permission.

Next steps#

List leaderboards
Prove GET /v1/leaderboards before creating anything.

Request

Header Params

Body Params application/jsonRequired

Examples

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
Request Request Example
Shell
JavaScript
Java
Swift
curl --location 'https://sgtr-api.returning.ai/v1/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": 600, "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": 600, "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:24
Previous
List leaderboards with pagination
Next
Update an existing leaderboard
Built with