Tiers API
Query the current tier for a participant and manually assign tiers. Automatic tiers are evaluated on every points award — when a participant crosses a threshold, the tier upgrade is returned in the points response.
Authentication: All endpoints require an
X-API-Key header. Base URL: https://YOUR_API_DOMAIN/api/v1/gamify| Method | Endpoint | Description |
|---|---|---|
| GET | /gamify/participants/{pid}/tier | Current tier, next tier, and tier history. |
| POST | /gamify/tiers/assign | Manually assign a tier (overrides automatic). |
Get Current Tier
Returns the participant's current tier, progress toward the next tier, and full tier history.
GET /api/v1/gamify/participants/user_123/tier
{
"participant_id": "user_123",
"current_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
},
"tier_history": [
{ "code": "bronze", "achieved_at": "2026-01-01T..." },
{ "code": "silver", "achieved_at": "2026-01-15T..." },
{ "code": "gold", "achieved_at": "2026-02-01T..." }
]
}Manual Tier Assignment
Override automatic tier evaluation and assign a specific tier. Useful for VIP promotions, support escalations, or manual corrections.
POST /api/v1/gamify/tiers/assign
{
"participant_id": "user_123",
"tier_code": "platinum",
"reason": "VIP promotion"
}