Get Campaign Leaderboard

GET /v1/campaigns/{slug}/leaderboard

Returns the campaign leaderboard ranked by total points. Useful for displaying rankings in your app or verifying participant standings.

Authentication

Header	Required	Value
X-API-Secret	Yes	Your secret key

Query Parameters

Parameter	Type	Default	Description
limit	integer	20	Number of entries to return (max 100)

Request Examples

cURL

curl -X GET "https://api.gamifyhost.com/v1/campaigns/summer-promo/leaderboard?limit=10" \
  -H "X-API-Secret: sk_live_your_secret_key"

JavaScript

const response = await fetch(
  'https://api.gamifyhost.com/v1/campaigns/summer-promo/leaderboard?limit=10',
  {
    headers: { 'X-API-Secret': 'sk_live_your_secret_key' },
  }
);

const data = await response.json();
data.data.entries.forEach(e =>
  console.log(`#${e.rank} ${e.displayName} — ${e.totalPoints} pts`)
);

Python

import requests

response = requests.get(
    "https://api.gamifyhost.com/v1/campaigns/summer-promo/leaderboard",
    headers={"X-API-Secret": "sk_live_your_secret_key"},
    params={"limit": 10},
)

data = response.json()
for entry in data["data"]["entries"]:
    print(f"#{entry['rank']} {entry['displayName']} — {entry['totalPoints']} pts")

Java

import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.net.URI;

HttpClient client = HttpClient.newHttpClient();

HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://api.gamifyhost.com/v1/campaigns/summer-promo/leaderboard?limit=10"))
    .header("X-API-Secret", "sk_live_your_secret_key")
    .GET()
    .build();

HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());

Go

req, _ := http.NewRequest("GET", "https://api.gamifyhost.com/v1/campaigns/summer-promo/leaderboard?limit=10", nil)
req.Header.Set("X-API-Secret", "sk_live_your_secret_key")

resp, err := http.DefaultClient.Do(req)
if err != nil {
    log.Fatal(err)
}
defer resp.Body.Close()

var result map[string]interface{}
json.NewDecoder(resp.Body).Decode(&result)
fmt.Println(result["data"])

PHP

$ch = curl_init('https://api.gamifyhost.com/v1/campaigns/summer-promo/leaderboard?limit=10');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'X-API-Secret: sk_live_your_secret_key',
    ],
]);

$response = curl_exec($ch);
curl_close($ch);

$data = json_decode($response, true);
foreach ($data['data']['entries'] as $entry) {
    echo "#{$entry['rank']} {$entry['displayName']} — {$entry['totalPoints']} pts\n";
}

Ruby

require 'net/http'
require 'json'

uri = URI('https://api.gamifyhost.com/v1/campaigns/summer-promo/leaderboard?limit=10')
req = Net::HTTP::Get.new(uri)
req['X-API-Secret'] = 'sk_live_your_secret_key'

res = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) { |http| http.request(req) }
data = JSON.parse(res.body)
data['data']['entries'].each do |entry|
  puts "##{entry['rank']} #{entry['displayName']} — #{entry['totalPoints']} pts"
end

C#

using var client = new HttpClient();
client.DefaultRequestHeaders.Add("X-API-Secret", "sk_live_your_secret_key");

var response = await client.GetAsync(
    "https://api.gamifyhost.com/v1/campaigns/summer-promo/leaderboard?limit=10");
var json = await response.Content.ReadAsStringAsync();
Console.WriteLine(json);

Dart

import 'dart:convert';
import 'package:http/http.dart' as http;

final response = await http.get(
  Uri.parse('https://api.gamifyhost.com/v1/campaigns/summer-promo/leaderboard?limit=10'),
  headers: {'X-API-Secret': 'sk_live_your_secret_key'},
);

final data = jsonDecode(response.body);
for (final entry in data['data']['entries']) {
  print('#${entry['rank']} ${entry['displayName']} — ${entry['totalPoints']} pts');
}

Response

Status: 200 OK

{
  "status": "success",
  "data": {
    "entries": [
      {
        "rank": 1,
        "userId": "user_abc",
        "displayName": "Alice",
        "totalPoints": 2500,
        "eventsCount": 12
      },
      {
        "rank": 2,
        "userId": "user_def",
        "displayName": "Bob",
        "totalPoints": 1800,
        "eventsCount": 8
      }
    ],
    "totalParticipants": 156
  }
}

Response Fields

Field	Type	Description
entries	array	Ranked list of participants
entries[].rank	integer	Position on the leaderboard
entries[].userId	string	User’s external ID
entries[].displayName	string	User’s display name
entries[].totalPoints	integer	Total points earned in this campaign
entries[].eventsCount	integer	Number of events recorded
totalParticipants	integer	Total campaign participants