Participants API
Register participants explicitly, get rich profiles with all gamification data, update profile attributes, and query unified state. Participants are also auto-created on first interaction with any other endpoint.
Authentication: All endpoints require an
X-API-Key header. Base URL: https://YOUR_API_DOMAIN/api/v1/gamify| Method | Endpoint | Description |
|---|---|---|
| POST | /gamify/participants | Create/register a participant with profile data. Idempotent. |
| GET | /gamify/participants/{pid} | Rich profile with points, tier, badges, streaks, rewards. |
| PATCH | /gamify/participants/{pid} | Update display name, avatar, or custom attributes. |
| GET | /gamify/participants/{pid}/state | Unified state with selectable sections. |
Create Participant
Idempotent — calling again with the same participant_id updates display_name, avatar, and attributes.
POST /api/v1/gamify/participants
{
"participant_id": "user_123", // Required, your app's user ID
"display_name": "Jane Doe", // Optional
"avatar_url": "https://example.com/avatar.png", // Optional
"attributes": { // Optional, custom metadata
"plan": "premium",
"signup_source": "referral"
}
}
// Response (201 Created)
{
"participant_id": "user_123",
"display_name": "Jane Doe",
"avatar_url": "https://example.com/avatar.png",
"attributes": { "plan": "premium", "signup_source": "referral" },
"points": { "balance": 0, "total_earned": 0, "total_spent": 0 },
"tier": null,
"badges": [],
"streaks": null,
"rewards_claimed": 0,
"total_events": 0,
"is_active": true,
"created_at": "2026-02-14T10:00:00Z"
}Get Participant Profile
Returns a rich profile with points breakdown, current tier with next-tier progress, earned badges, best streak, and rewards count.
GET /api/v1/gamify/participants/user_123
{
"participant_id": "user_123",
"display_name": "Jane Doe",
"avatar_url": "https://example.com/avatar.png",
"attributes": { "plan": "premium" },
"points": { "balance": 1500, "total_earned": 5000, "total_spent": 3500 },
"tier": {
"code": "gold", "name": "Gold", "level": 3, "color": "#FFD700",
"achieved_at": "2026-02-01T10:00:00Z",
"next_tier": { "code": "platinum", "name": "Platinum",
"points_required": 10000, "points_remaining": 8500 }
},
"badges": [
{ "code": "first_steps", "name": "First Steps", "rarity": "common",
"earned": true, "earned_at": "2026-01-15T..." }
],
"streaks": { "current": 7, "longest": 21, "last_activity_at": "2026-02-14T..." },
"rewards_claimed": 3,
"total_events": 156,
"first_seen_at": "2026-01-01T...",
"last_seen_at": "2026-02-14T...",
"is_active": true
}Update Participant
PATCH /api/v1/gamify/participants/user_123
{
"display_name": "Jane Smith",
"attributes": { "plan": "enterprise", "team_id": "team_42" }
}
// Returns full profile (same shape as GET)Unified State
Lightweight endpoint that returns selected gamification sections without full profile data.
// Full state
GET /api/v1/gamify/participants/user_123/state
// Partial state (only specific sections)
GET /api/v1/gamify/participants/user_123/state?include=points,tier,badges
// Response
{
"participant_id": "user_123",
"points": { "balance": 1500, "total_earned": 5000, "total_spent": 3500 },
"tier": { "code": "gold", "name": "Gold", "level": 3 },
"badges": [
{ "code": "first_steps", "earned": true, "earned_at": "..." },
{ "code": "power_user", "earned": false, "earned_at": null }
],
"streaks": { "current": 7, "longest": 21 },
"challenges": { "active": 2, "completed": 5 },
"rewards": { "total_claimed": 3 }
}Include parameter: Comma-separated list of sections to return. Options:
points, tier, badges, streaks, challenges, rewards. Omit to return all sections.