Bestenliste

Rufen Sie eine Rangliste für jeden Wettbewerb ab. Virale und Empfehlungs-Kampagnen werden nach Punkten sortiert; Affiliate-Kampagnen nach verdienten Provisionen.

Bestenliste abrufen

GET/api/v1/contests/:contestId/leaderboard

Public or Private API Key

Gibt eine Rangliste der Wettbewerbseinträge zurück. Es werden nur bestätigte, nicht disqualifizierte Einträge berücksichtigt.

Virale / Empfehlungs-Kampagnen: sortiert nach points absteigend
Affiliate-Kampagnen: sortiert nach commission (totalCommissionEarned) absteigend

Die Antwort enthält ein oberstes metric-Feld ("points" oder "commission"), das angibt, welcher Wert die Rangfolge bestimmt.

Pfadparameter

contestIdstring required

Die eindeutige Wettbewerbs-ID

Abfrageparameter

limitnumber

Anzahl der zurückzugebenden Einträge (1-100). Standard: 25

Anfrage

bash

curl -X GET "https://blitzrocket.com/api/v1/contests/clx1abc123/leaderboard?limit=10" \
  -H "x-api-key: your_api_key_here"

javascript

const contestId = "clx1abc123";
const response = await fetch(
  `https://blitzrocket.com/api/v1/contests/${contestId}/leaderboard?limit=10`,
  {
    headers: { "x-api-key": "your_api_key_here" },
  }
);

const { data } = await response.json();
data.forEach((entry) => {
  console.log(`#${entry.rank} ${entry.name || entry.email}: ${entry.points} pts`);
});

python

import requests

contest_id = "clx1abc123"
response = requests.get(
    f"https://blitzrocket.com/api/v1/contests/{contest_id}/leaderboard",
    headers={"x-api-key": "your_api_key_here"},
    params={"limit": 10}
)

data = response.json()["data"]
for entry in data:
    name = entry.get("name") or entry["email"]
    print(f"#{entry['rank']} {name}: {entry['points']} pts")

Antwort

json

{
  "success": true,
  "metric": "points",
  "data": [
    {
      "rank": 1,
      "id": "entry_abc123",
      "email": "jane@example.com",
      "name": "Jane Doe",
      "points": 350,
      "commission": 0,
      "referralCode": "REF-XYZ789",
      "referralsCount": 12,
      "joinedAt": "2025-06-01T10:00:00.000Z"
    },
    {
      "rank": 2,
      "id": "entry_def456",
      "email": "john@example.com",
      "name": "John Smith",
      "points": 280,
      "referralCode": "REF-ABC456",
      "referralsCount": 8,
      "joinedAt": "2025-06-02T14:30:00.000Z"
    },
    {
      "rank": 3,
      "id": "entry_ghi789",
      "email": "alex@example.com",
      "name": null,
      "points": 195,
      "referralCode": "REF-DEF123",
      "referralsCount": 3,
      "joinedAt": "2025-06-03T09:15:00.000Z"
    }
  ]
}

Antwortfelder

ranknumber

Position in der Bestenliste (1-basiert)

idstring

Eindeutige Eintrags-ID

emailstring

E-Mail-Adresse des Teilnehmers

namestring | null

Name des Teilnehmers

pointsnumber

Gesamtpunktzahl

commissionnumber

Gesamtverdiente Provision in Dollar (Affiliate-Kampagnen)

metricstring

Ranking-Metrik für diesen Wettbewerb: Punkte oder Provision

referralCodestring | null

Empfehlungscode des Teilnehmers

referralsCountnumber

Anzahl erfolgreicher Empfehlungen

joinedAtstring

ISO 8601 Zeitstempel, wann der Teilnehmer beigetreten ist

Nutzungshinweise

Gibt nur Einträge zurück, bei denen emailConfirmed auf true und disqualified auf false gesetzt ist
Ergebnisse sind je nach Kampagnenmodus nach points oder commission sortiert
Der Parameter limit akzeptiert Werte zwischen 1 und 100
Verwenden Sie diesen Endpunkt mit einem öffentlichen Schlüssel, um clientseitige Bestenlisten-Widgets zu erstellen

javascript

async function renderLeaderboard(contestId, container) {
  const response = await fetch(
    `https://blitzrocket.com/api/v1/contests/${contestId}/leaderboard?limit=10`,
    {
      headers: { "x-api-key": "your_public_key_here" },
    }
  );

  const { data } = await response.json();

  container.innerHTML = data
    .map(
      (entry) => `
      <div class="leaderboard-entry">
        <span class="rank">#${entry.rank}</span>
        <span class="name">${entry.name || "Anonym"}</span>
        <span class="points">${entry.points} pts</span>
        <span class="referrals">${entry.referralsCount} Empfehlungen</span>
      </div>
    `
    )
    .join("");
}

Fehlerantworten

Status	Fehler	Beschreibung
`400`	Fehlende contestId	Der Pfadparameter contestId ist erforderlich
`401`	Ungültiger API-Schlüssel	API-Schlüssel fehlt oder ist ungültig
`404`	Wettbewerb nicht gefunden	Kein Wettbewerb mit der angegebenen ID vorhanden