---
title: Leaderboard Entity & CRUD
url: https://docs.kaltura.com/docs/events-collaboration/gamification-api/gamification-leaderboard-entity-crud
---

## Leaderboard Entity & CRUD

Leaderboards track user scores and rank users. They are scoped to virtual events via `virtualEventIds`.

### 4.1 Leaderboard Entity

| Field | Type | Description |
|-------|------|-------------|
| `id` | string | Auto-generated unique identifier (read-only) |
| `name` | string | Leaderboard display name |
| `description` | string | Description text |
| `status` | string | `scheduled`, `enabled`, `disabled` |
| `startDate` | ISO 8601 | Scoring window start |
| `endDate` | ISO 8601 | Scoring window end |
| `virtualEventIds` | int[] | Virtual event IDs this leaderboard applies to |
| `participationPolicy` | object | Controls user visibility (see section 5) |
| `subLeaderboards` | array | Segments for team/regional rankings (see section 4.4) |

**Status lifecycle:** `scheduled` → `enabled` → `disabled`. Create leaderboards as `scheduled`, then update to `enabled` when the event starts.

### 4.2 Create Leaderboard

**Parameters**

| Parameter | Type | Required | Description |
|---|---|---|---|
| `objectType` | string | Yes | Always `"Leaderboard"` |
| `name` | string | Yes | Leaderboard display name |
| `description` | string | No | Description text |
| `status` | string | Yes | Initial status: `"scheduled"`, `"enabled"`, or `"disabled"` |
| `startDate` | string | Yes | Scoring window start in ISO 8601 format |
| `endDate` | string | Yes | Scoring window end in ISO 8601 format |
| `virtualEventIds` | array | Yes | Array of virtual event ID strings this leaderboard applies to |
| `participationPolicy` | object | No | Controls user visibility (see section 5). Default: all users visible |
| `participationPolicy.userDefaultPolicy` | string | No | Default policy: `"display"`, `"do_not_display"`, or `"do_not_save"` |
| `participationPolicy.policies` | array | No | Array of policy override objects with `policy`, `matchCriteria`, and `values` |
| `subLeaderboards` | array | No | Segment definitions for team/regional rankings (see section 4.4) |

```bash
curl -X POST "$KALTURA_SCM_URL/leaderboard/create" \
  -H "Authorization: Bearer $KALTURA_KS" \
  -H "Content-Type: application/json" \
  -d '{
    "objectType": "Leaderboard",
    "name": "Conference Engagement",
    "description": "Points for session attendance, polls, and chat",
    "status": "scheduled",
    "startDate": "2025-06-01T09:00:00.000Z",
    "endDate": "2025-06-03T18:00:00.000Z",
    "participationPolicy": {
      "userDefaultPolicy": "display",
      "policies": []
    },
    "virtualEventIds": ["$VIRTUAL_EVENT_ID"]
  }'
```

**Response**

```json
{
  "id": "lb_abc123",
  "name": "Conference Engagement",
  "description": "Points for session attendance, polls, and chat",
  "status": "scheduled",
  "startDate": "2025-06-01T09:00:00.000Z",
  "endDate": "2025-06-03T18:00:00.000Z",
  "participationPolicy": {
    "userDefaultPolicy": "display",
    "policies": []
  },
  "virtualEventIds": ["12345"],
  "createdAt": "2025-05-20T10:00:00.000Z",
  "updatedAt": "2025-05-20T10:00:00.000Z"
}
```

### 4.3 Get, Update, List, Delete

```bash
# Get
curl -X POST "$KALTURA_SCM_URL/leaderboard/get" \
  -H "Authorization: Bearer $KALTURA_KS" \
  -H "Content-Type: application/json" \
  -d '{"id": "'$LEADERBOARD_ID'"}'

# Update (enable when event starts)
curl -X POST "$KALTURA_SCM_URL/leaderboard/update" \
  -H "Authorization: Bearer $KALTURA_KS" \
  -H "Content-Type: application/json" \
  -d '{"id": "'$LEADERBOARD_ID'", "status": "enabled"}'

# List (paginated)
curl -X POST "$KALTURA_SCM_URL/leaderboard/list" \
  -H "Authorization: Bearer $KALTURA_KS" \
  -H "Content-Type: application/json" \
  -d '{"pager": {"pageSize": 10, "pageIndex": 1}}'

# Delete
curl -X POST "$KALTURA_SCM_URL/leaderboard/delete" \
  -H "Authorization: Bearer $KALTURA_KS" \
  -H "Content-Type: application/json" \
  -d '{"id": "'$LEADERBOARD_ID'"}'
```

### 4.4 Sub-Leaderboards

Segment users by properties (country, company, department) for team-based or regional competitions.

```bash
curl -X POST "$KALTURA_SCM_URL/leaderboard/create" \
  -H "Authorization: Bearer $KALTURA_KS" \
  -H "Content-Type: application/json" \
  -d '{
    "objectType": "Leaderboard",
    "name": "Regional Competition",
    "status": "scheduled",
    "startDate": "2025-06-01T00:00:00Z",
    "endDate": "2025-06-02T00:00:00Z",
    "participationPolicy": {"userDefaultPolicy": "display", "policies": []},
    "virtualEventIds": ["$VIRTUAL_EVENT_ID"],
    "subLeaderboards": [
      {"name": "By Country", "filterPaths": ["country"], "id": 0},
      {"name": "By Company", "filterPaths": ["company"], "id": 1}
    ]
  }'
```

`filterPaths` references user profile properties from the [User Profile API](/docs/events-collaboration/user-profile-api/user-profile-overview). Individual scores automatically aggregate within their sub-leaderboard segment.