Skip to main content
POST
/
admin
/
projects
/
{projectId}
/
leaderboards
Create a new leaderboard
curl --request POST \
  --url https://api.engagefabric.com/admin/projects/{projectId}/leaderboards \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "name": "Weekly XP Champions",
  "type": "GLOBAL",
  "metric": "xp",
  "sortOrder": "DESC",
  "description": "Top players by XP earned this week",
  "startDate": "2025-01-01T00:00:00Z",
  "endDate": "2025-01-31T23:59:59Z",
  "resetSchedule": "DAILY",
  "segmentField": "metadata.region",
  "maxEntries": 1000,
  "minScore": 0,
  "showTopN": 100,
  "iconUrl": "https://cdn.example.com/icons/trophy.png",
  "metadata": {
    "theme": "gold",
    "category": "competitive"
  }
}
'

Authorizations

​
Authorization
string
header
required

JWT token for admin console authentication

Path Parameters

​
projectId
string
required

Project ID

Body

application/json
​
name
string
required

Leaderboard name

Maximum string length: 255
Example:

"Weekly XP Champions"

​
type
enum<string>
default:GLOBAL
required

Leaderboard type

Available options:
GLOBAL,
SEGMENTED,
TIME_BOXED,
SEASONAL
​
metric
string
required

Metric to rank by (e.g., "xp", "wins", "points")

Maximum string length: 100
Example:

"xp"

​
sortOrder
enum<string>
default:DESC
required

Sort order for rankings

Available options:
ASC,
DESC
​
description
string

Leaderboard description

Example:

"Top players by XP earned this week"

​
startDate
string<date-time>

Start date for time-boxed leaderboards

Example:

"2025-01-01T00:00:00Z"

​
endDate
string<date-time>

End date for time-boxed leaderboards

Example:

"2025-01-31T23:59:59Z"

​
resetSchedule
enum<string>

Reset schedule for recurring leaderboards

Available options:
DAILY,
WEEKLY,
MONTHLY,
SEASONAL
​
segmentField
string

Field to segment by (e.g., "metadata.region")

Maximum string length: 255
Example:

"metadata.region"

​
maxEntries
number
default:1000

Maximum entries to track

Required range: 10 <= x <= 100000
​
minScore
number

Minimum score to appear on leaderboard

Example:

0

​
showTopN
number
default:100

Number of top entries to show by default

Required range: 1 <= x <= 1000
​
iconUrl
string

Icon URL for the leaderboard

Example:

"https://cdn.example.com/icons/trophy.png"

​
metadata
object

Additional metadata

Example:
{
  "theme": "gold",
  "category": "competitive"
}

Response

Leaderboard created successfully