Leaderboard Entity & CRUD - Gamification

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)

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

{
  "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

# 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.

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. Individual scores automatically aggregate within their sub-leaderboard segment.