Points API
Query point balances and transaction history for participants within an engagement.
Authentication: Session-based. Pass
session_id and engagement_id in the request body. No API key required.Endpoints
| Method | Endpoint | Description |
|---|---|---|
| POST | /points/balance | Get current point balance |
| POST | /points/transactions | Get point transaction history |
Get Balance
Returns the participant's current available points and lifetime total. Available points reflect the spendable balance after redemptions, while total points track lifetime earnings.
curl -X POST https://YOUR_API_DOMAIN/api/v1/points/balance \
-H "Content-Type: application/json" \
-d '{
"session_id": "sess_abc123",
"engagement_id": "550e8400-e29b-41d4-a716-446655440000"
}'Response
{
"available_points": 350,
"total_points": 500,
"currency_name": "Points",
"last_earned_at": "2026-04-10T14:30:00Z"
}Note:
total_points is never decremented by redemptions. It tracks lifetime earnings used for tier qualification and leaderboard ranking. Only available_points decreases on spend.Get Transactions
Returns a paginated list of point transactions, including awards, bonuses, and redemptions.
curl -X POST https://YOUR_API_DOMAIN/api/v1/points/transactions \
-H "Content-Type: application/json" \
-d '{
"session_id": "sess_abc123",
"engagement_id": "550e8400-e29b-41d4-a716-446655440000",
"limit": 10,
"offset": 0
}'Response
{
"transactions": [
{
"id": "txn_001",
"type": "award",
"amount": 100,
"reason": "Quiz completed",
"activity_id": "quiz_1",
"created_at": "2026-04-10T14:30:00Z"
},
{
"id": "txn_002",
"type": "award",
"amount": 50,
"reason": "Spin wheel bonus",
"activity_id": "spin_1",
"created_at": "2026-04-10T14:25:00Z"
},
{
"id": "txn_003",
"type": "redemption",
"amount": -150,
"reason": "Reward claimed: 20% Off Coupon",
"created_at": "2026-04-10T14:31:00Z"
}
],
"total": 3,
"has_more": false
}