Activities API
Validate activity submissions, complete activities with on-completion actions, and check participation eligibility.
Authentication: Session-based. Pass
session_id and engagement_id in the request body. No API key required.Endpoints
| Method | Endpoint | Description |
|---|---|---|
| POST | /activities/{activityId}/validate | Server-side validation (spin wheel results, quiz scoring) |
| POST | /activities/{activityId}/complete-with-actions | Complete activity and execute all on-completion actions |
| GET | /activities/{activityId}/eligibility | Check participation limits (max attempts, cooldown) |
Validate Activity
Performs server-side validation before completion. Used for spin wheel result calculation, quiz answer scoring, and other activities that require server-authoritative results.
curl -X POST https://YOUR_API_DOMAIN/api/v1/activities/{activityId}/validate \
-H "Content-Type: application/json" \
-d '{
"session_id": "sess_abc123",
"engagement_id": "550e8400-e29b-41d4-a716-446655440000",
"activity_type": "spin_wheel",
"payload": {
"spin_result_index": 3
}
}'Response
{
"valid": true,
"result": {
"segment_index": 3,
"prize_label": "20% Off",
"prize_type": "coupon"
}
}Complete with Actions
Completes an activity and atomically executes all configured on-completion actions (award points, grant badges, claim rewards). Returns the combined results of all actions.
curl -X POST https://YOUR_API_DOMAIN/api/v1/activities/{activityId}/complete-with-actions \
-H "Content-Type: application/json" \
-d '{
"session_id": "sess_abc123",
"engagement_id": "550e8400-e29b-41d4-a716-446655440000",
"activity_type": "quiz",
"payload": {
"answers": [
{"question_id": "q1", "selected_option": 2},
{"question_id": "q2", "selected_option": 0}
],
"score": 80,
"passed": true
}
}'Response
{
"success": true,
"actions_executed": [
{
"type": "award_points",
"points_awarded": 100,
"new_balance": 350
},
{
"type": "award_reward",
"reward_claimed": {
"reward_id": "rwd_123",
"code": "SAVE20",
"display_type": "coupon",
"title": "20% Off Your Next Order"
}
}
],
"fact_id": "fact_789"
}Check Eligibility
Checks whether a participant is eligible to attempt an activity, based on max attempt limits and cooldown periods.
curl -X GET "https://YOUR_API_DOMAIN/api/v1/activities/{activityId}/eligibility?session_id=sess_abc123&engagement_id=550e8400-e29b-41d4-a716-446655440000"Response
{
"eligible": true,
"attempts_used": 1,
"max_attempts": 3,
"cooldown_remaining_seconds": 0
}When ineligible
{
"eligible": false,
"attempts_used": 3,
"max_attempts": 3,
"cooldown_remaining_seconds": 3600
}