Create leaderboards

JavaScript

import { TrophyApiClient } from '@trophyso/node';

const trophy = new TrophyApiClient({
  apiKey: 'YOUR_API_KEY'
});

const response = await trophy.admin.leaderboards.create([
  {
    name: 'Revenue Champions',
    key: 'revenue-champions',
    status: 'inactive',
    rankBy: 'metric',
    metricId: '550e8400-e29b-41d4-a716-446655440000',
    maxParticipants: 100,
    start: '2026-04-20'
  },
  {
    name: 'Streak Legends',
    key: 'streak-legends',
    status: 'scheduled',
    rankBy: 'streak',
    start: '2026-04-27'
  }
]);

from trophy import TrophyApi

client = TrophyApi(api_key='YOUR_API_KEY')

response = client.admin.leaderboards.create([
  {
    "name": "Revenue Champions",
    "key": "revenue-champions",
    "status": "inactive",
    "rankBy": "metric",
    "metricId": "550e8400-e29b-41d4-a716-446655440000",
    "maxParticipants": 100,
    "start": "2026-04-20"
  },
  {
    "name": "Streak Legends",
    "key": "streak-legends",
    "status": "scheduled",
    "rankBy": "streak",
    "start": "2026-04-27"
  }
])

import (
  "context"

  api "github.com/trophyso/trophy-go"
  trophyclient "github.com/trophyso/trophy-go/client"
  "github.com/trophyso/trophy-go/option"
)

client := trophyclient.NewClient(
  option.WithApiKey("YOUR_API_KEY"),
)

response, err := client.Admin.Leaderboards.Create(context.TODO(), api.CreateLeaderboardsRequest{})

curl --request POST \
  --url https://admin.trophy.so/v1/leaderboards \
  --header 'Content-Type: application/json' \
  --header 'X-API-KEY: <api-key>' \
  --data '
[
  {
    "name": "Revenue Champions",
    "key": "revenue-champions",
    "status": "inactive",
    "rankBy": "metric",
    "metricId": "550e8400-e29b-41d4-a716-446655440000",
    "maxParticipants": 100,
    "start": "2026-04-20",
    "breakdownAttributes": [
      "550e8400-e29b-41d4-a716-446655440010"
    ],
    "runUnit": "month",
    "runInterval": 1
  },
  {
    "name": "Streak Legends",
    "key": "streak-legends",
    "status": "scheduled",
    "rankBy": "streak",
    "start": "2026-04-27"
  }
]
'

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://admin.trophy.so/v1/leaderboards",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    [
        'name' => 'Revenue Champions',
        'key' => 'revenue-champions',
        'status' => 'inactive',
        'rankBy' => 'metric',
        'metricId' => '550e8400-e29b-41d4-a716-446655440000',
        'maxParticipants' => 100,
        'start' => '2026-04-20',
        'breakdownAttributes' => [
                '550e8400-e29b-41d4-a716-446655440010'
        ],
        'runUnit' => 'month',
        'runInterval' => 1
    ],
    [
        'name' => 'Streak Legends',
        'key' => 'streak-legends',
        'status' => 'scheduled',
        'rankBy' => 'streak',
        'start' => '2026-04-27'
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json",
    "X-API-KEY: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

HttpResponse<String> response = Unirest.post("https://admin.trophy.so/v1/leaderboards")
  .header("X-API-KEY", "<api-key>")
  .header("Content-Type", "application/json")
  .body("[\n  {\n    \"name\": \"Revenue Champions\",\n    \"key\": \"revenue-champions\",\n    \"status\": \"inactive\",\n    \"rankBy\": \"metric\",\n    \"metricId\": \"550e8400-e29b-41d4-a716-446655440000\",\n    \"maxParticipants\": 100,\n    \"start\": \"2026-04-20\",\n    \"breakdownAttributes\": [\n      \"550e8400-e29b-41d4-a716-446655440010\"\n    ],\n    \"runUnit\": \"month\",\n    \"runInterval\": 1\n  },\n  {\n    \"name\": \"Streak Legends\",\n    \"key\": \"streak-legends\",\n    \"status\": \"scheduled\",\n    \"rankBy\": \"streak\",\n    \"start\": \"2026-04-27\"\n  }\n]")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://admin.trophy.so/v1/leaderboards")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["X-API-KEY"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "[\n  {\n    \"name\": \"Revenue Champions\",\n    \"key\": \"revenue-champions\",\n    \"status\": \"inactive\",\n    \"rankBy\": \"metric\",\n    \"metricId\": \"550e8400-e29b-41d4-a716-446655440000\",\n    \"maxParticipants\": 100,\n    \"start\": \"2026-04-20\",\n    \"breakdownAttributes\": [\n      \"550e8400-e29b-41d4-a716-446655440010\"\n    ],\n    \"runUnit\": \"month\",\n    \"runInterval\": 1\n  },\n  {\n    \"name\": \"Streak Legends\",\n    \"key\": \"streak-legends\",\n    \"status\": \"scheduled\",\n    \"rankBy\": \"streak\",\n    \"start\": \"2026-04-27\"\n  }\n]"

response = http.request(request)
puts response.read_body

{
  "created": [
    {
      "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "name": "<string>",
      "key": "<string>",
      "maxParticipants": 123,
      "start": "2023-12-25",
      "breakdownAttributes": [
        "3c90c3cc-0d44-4b50-8888-8dd25736052a"
      ],
      "description": "<string>",
      "metricId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "pointsSystemId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "end": "2023-12-25",
      "startTime": "09:00",
      "endTime": "17:00",
      "runInterval": 123
    }
  ],
  "issues": [
    {
      "severity": "warning",
      "message": "Would exceed maximum freeze limit",
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "userId": "user-123",
      "boostId": "550e8400-e29b-41d4-a716-446655440000",
      "index": 0
    }
  ]
}

{
  "created": [
    {
      "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "name": "<string>",
      "key": "<string>",
      "maxParticipants": 123,
      "start": "2023-12-25",
      "breakdownAttributes": [
        "3c90c3cc-0d44-4b50-8888-8dd25736052a"
      ],
      "description": "<string>",
      "metricId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "pointsSystemId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "end": "2023-12-25",
      "startTime": "09:00",
      "endTime": "17:00",
      "runInterval": 123
    }
  ],
  "issues": [
    {
      "severity": "warning",
      "message": "Would exceed maximum freeze limit",
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "userId": "user-123",
      "boostId": "550e8400-e29b-41d4-a716-446655440000",
      "index": 0
    }
  ]
}

{
  "error": "<string>"
}

{
  "error": "<string>"
}

POST

leaderboards

JavaScript

import { TrophyApiClient } from '@trophyso/node';

const trophy = new TrophyApiClient({
  apiKey: 'YOUR_API_KEY'
});

const response = await trophy.admin.leaderboards.create([
  {
    name: 'Revenue Champions',
    key: 'revenue-champions',
    status: 'inactive',
    rankBy: 'metric',
    metricId: '550e8400-e29b-41d4-a716-446655440000',
    maxParticipants: 100,
    start: '2026-04-20'
  },
  {
    name: 'Streak Legends',
    key: 'streak-legends',
    status: 'scheduled',
    rankBy: 'streak',
    start: '2026-04-27'
  }
]);

from trophy import TrophyApi

client = TrophyApi(api_key='YOUR_API_KEY')

response = client.admin.leaderboards.create([
  {
    "name": "Revenue Champions",
    "key": "revenue-champions",
    "status": "inactive",
    "rankBy": "metric",
    "metricId": "550e8400-e29b-41d4-a716-446655440000",
    "maxParticipants": 100,
    "start": "2026-04-20"
  },
  {
    "name": "Streak Legends",
    "key": "streak-legends",
    "status": "scheduled",
    "rankBy": "streak",
    "start": "2026-04-27"
  }
])

import (
  "context"

  api "github.com/trophyso/trophy-go"
  trophyclient "github.com/trophyso/trophy-go/client"
  "github.com/trophyso/trophy-go/option"
)

client := trophyclient.NewClient(
  option.WithApiKey("YOUR_API_KEY"),
)

response, err := client.Admin.Leaderboards.Create(context.TODO(), api.CreateLeaderboardsRequest{})

curl --request POST \
  --url https://admin.trophy.so/v1/leaderboards \
  --header 'Content-Type: application/json' \
  --header 'X-API-KEY: <api-key>' \
  --data '
[
  {
    "name": "Revenue Champions",
    "key": "revenue-champions",
    "status": "inactive",
    "rankBy": "metric",
    "metricId": "550e8400-e29b-41d4-a716-446655440000",
    "maxParticipants": 100,
    "start": "2026-04-20",
    "breakdownAttributes": [
      "550e8400-e29b-41d4-a716-446655440010"
    ],
    "runUnit": "month",
    "runInterval": 1
  },
  {
    "name": "Streak Legends",
    "key": "streak-legends",
    "status": "scheduled",
    "rankBy": "streak",
    "start": "2026-04-27"
  }
]
'

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://admin.trophy.so/v1/leaderboards",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    [
        'name' => 'Revenue Champions',
        'key' => 'revenue-champions',
        'status' => 'inactive',
        'rankBy' => 'metric',
        'metricId' => '550e8400-e29b-41d4-a716-446655440000',
        'maxParticipants' => 100,
        'start' => '2026-04-20',
        'breakdownAttributes' => [
                '550e8400-e29b-41d4-a716-446655440010'
        ],
        'runUnit' => 'month',
        'runInterval' => 1
    ],
    [
        'name' => 'Streak Legends',
        'key' => 'streak-legends',
        'status' => 'scheduled',
        'rankBy' => 'streak',
        'start' => '2026-04-27'
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json",
    "X-API-KEY: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

HttpResponse<String> response = Unirest.post("https://admin.trophy.so/v1/leaderboards")
  .header("X-API-KEY", "<api-key>")
  .header("Content-Type", "application/json")
  .body("[\n  {\n    \"name\": \"Revenue Champions\",\n    \"key\": \"revenue-champions\",\n    \"status\": \"inactive\",\n    \"rankBy\": \"metric\",\n    \"metricId\": \"550e8400-e29b-41d4-a716-446655440000\",\n    \"maxParticipants\": 100,\n    \"start\": \"2026-04-20\",\n    \"breakdownAttributes\": [\n      \"550e8400-e29b-41d4-a716-446655440010\"\n    ],\n    \"runUnit\": \"month\",\n    \"runInterval\": 1\n  },\n  {\n    \"name\": \"Streak Legends\",\n    \"key\": \"streak-legends\",\n    \"status\": \"scheduled\",\n    \"rankBy\": \"streak\",\n    \"start\": \"2026-04-27\"\n  }\n]")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://admin.trophy.so/v1/leaderboards")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["X-API-KEY"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "[\n  {\n    \"name\": \"Revenue Champions\",\n    \"key\": \"revenue-champions\",\n    \"status\": \"inactive\",\n    \"rankBy\": \"metric\",\n    \"metricId\": \"550e8400-e29b-41d4-a716-446655440000\",\n    \"maxParticipants\": 100,\n    \"start\": \"2026-04-20\",\n    \"breakdownAttributes\": [\n      \"550e8400-e29b-41d4-a716-446655440010\"\n    ],\n    \"runUnit\": \"month\",\n    \"runInterval\": 1\n  },\n  {\n    \"name\": \"Streak Legends\",\n    \"key\": \"streak-legends\",\n    \"status\": \"scheduled\",\n    \"rankBy\": \"streak\",\n    \"start\": \"2026-04-27\"\n  }\n]"

response = http.request(request)
puts response.read_body

{
  "created": [
    {
      "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "name": "<string>",
      "key": "<string>",
      "maxParticipants": 123,
      "start": "2023-12-25",
      "breakdownAttributes": [
        "3c90c3cc-0d44-4b50-8888-8dd25736052a"
      ],
      "description": "<string>",
      "metricId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "pointsSystemId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "end": "2023-12-25",
      "startTime": "09:00",
      "endTime": "17:00",
      "runInterval": 123
    }
  ],
  "issues": [
    {
      "severity": "warning",
      "message": "Would exceed maximum freeze limit",
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "userId": "user-123",
      "boostId": "550e8400-e29b-41d4-a716-446655440000",
      "index": 0
    }
  ]
}

{
  "created": [
    {
      "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "name": "<string>",
      "key": "<string>",
      "maxParticipants": 123,
      "start": "2023-12-25",
      "breakdownAttributes": [
        "3c90c3cc-0d44-4b50-8888-8dd25736052a"
      ],
      "description": "<string>",
      "metricId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "pointsSystemId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "end": "2023-12-25",
      "startTime": "09:00",
      "endTime": "17:00",
      "runInterval": 123
    }
  ],
  "issues": [
    {
      "severity": "warning",
      "message": "Would exceed maximum freeze limit",
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "userId": "user-123",
      "boostId": "550e8400-e29b-41d4-a716-446655440000",
      "index": 0
    }
  ]
}

{
  "error": "<string>"
}

{
  "error": "<string>"
}

Authorizations

X-API-KEY

string

header

required

Headers

Tenant-ID

string

The tenant identifier for multi-tenant organisations. Required when the organisation has multi-tenancy enabled. Pass your own internal customer ID for the tenant. Ignored for single-tenant organisations.

Body

application/json

Array of leaderboards to create.

Required array length: 1 - 100 elements

name

string

required

The leaderboard name.

Example:

"Revenue Champions"

key

string

required

The leaderboard key. Only alphanumeric characters, hyphens, and underscores are permitted.

Pattern: ^[a-zA-Z\d-_]+$

Example:

"revenue-champions"

rankBy

enum<string>

required

What the leaderboard ranks by.

Available options:

metric,

streak,

points

Example:

"metric"

description

string

The leaderboard description.

Example:

"Ranked by monthly revenue"

status

enum<string>

default:inactive

The initial user-facing status. Defaults to inactive. Use scheduled for leaderboards that should be active in the future and finished only when creating a leaderboard with an end date in the past.

Available options:

inactive,

active,

scheduled,

finished

Example:

"inactive"

metricId

string<uuid>

The metric ID to rank by when rankBy is metric.

pointsSystemId

string<uuid>

The points system ID to rank by when rankBy is points.

maxParticipants

integer | null

default:1000

The maximum number of participants. Defaults to 1000.

Required range: 1 <= x <= 1000

Example:

100

start

string<date>

The leaderboard start date in YYYY-MM-DD format. Defaults to today when omitted.

Example:

"2026-04-20"

end

string<date>

The optional leaderboard end date in YYYY-MM-DD format.

Example:

"2026-05-20"

startTime

string

When set, ranking only counts activity at or after this time of day in the user's timezone (HH:mm format).

Pattern: ^([01][0-9]|2[0-3]):[0-5][0-9](:[0-5][0-9])?$

Example:

"09:00"

endTime

string

When set, ranking only counts activity before this time of day in the user's timezone (HH:mm format).

Pattern: ^([01][0-9]|2[0-3]):[0-5][0-9](:[0-5][0-9])?$

Example:

"17:00"

breakdownAttributes

string<uuid>[]

The UUIDs of the active user attributes to break rankings down by.

runUnit

enum<string>

How often the leaderboard repeats. Omit for a non-recurring leaderboard. Streak leaderboards cannot repeat.

Available options:

day,

month,

year

Example:

"month"

runInterval

integer

The number of runUnits between repeats. Required when runUnit is set.

Required range: x >= 1

Example:

1

Response

Successful operation (no leaderboards created)

Response containing created leaderboards and any per-item issues.

created

AdminLeaderboard · object[]

required

Array of successfully created leaderboards.

Show child attributes

issues

AdminIssue · object[]

required

Array of issues encountered during leaderboard creation.

Show child attributes

List leaderboards Delete leaderboards

⌘I

Overview

Metrics

Events

Attributes

Streaks

Points

Leaderboards

Tenants

Application API Keys

Admin

Authorizations

Headers

Body

Response