---
title: Badges
url: https://docs.kaltura.com/docs/events-collaboration/gamification-api/gamification-badges
---

## Badges

Badges reward users for completing a set of activity rules. A user either has a badge or does not — they are binary achievements.

### 7.1 Badge Entity

Rules are defined **inline** during badge creation (not via separate `rule/create` calls).

```bash
curl -X POST "$KALTURA_SCM_URL/badge/create" \
  -H "Authorization: Bearer $KALTURA_KS" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Session Attendee",
    "description": "Attend 3 sessions to earn this badge",
    "virtualEventIds": ["$VIRTUAL_EVENT_ID"],
    "iconUrl": "https://example.com/badges/attendee.png",
    "participationPolicy": {"userDefaultPolicy": "display", "policies": []},
    "rules": [
      {
        "name": "Watch 3 sessions",
        "conditions": [{"fact": "eventType", "operator": "equal", "value": "viewPeriod"}],
        "type": "countUnique",
        "metric": "entryId",
        "groupBy": "kuserId",
        "goal": "3",
        "points": "1",
        "maxPoints": "1"
      }
    ]
  }'
```

### 7.2 Badge Achievement Lifecycle

1. Analytics events are evaluated against each badge's rules
2. Per-user per-rule progress is tracked in `rulesData[]` (each has `id`, `progress`, `completed`)
3. When **all** rules have `completed: true`, badge status updates to `ACHIEVED` with `achievedTimestamp`

### 7.3 Badge CRUD

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

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

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

### 7.4 User Badge Progress

```bash
curl -X POST "$KALTURA_SCM_URL/userBadge/list" \
  -H "Authorization: Bearer $KALTURA_KS" \
  -H "Content-Type: application/json" \
  -d '{"gameObjectId": "'$BADGE_ID'", "pager": {"pageSize": 100, "pageIndex": 1}}'
```

Response:

```json
{
  "totalCount": 1,
  "objects": [{
    "userId": "user@example.com",
    "rulesData": [
      {"id": "rule1_id", "progress": 3, "completed": true}
    ],
    "status": "ACHIEVED",
    "achievedTimestamp": "2025-06-15T10:30:00Z"
  }]
}
```