Contests in headless gamification

List active contests

Returns up to 20 currently-active contests, optionally filtered to those wired to a specific engagement.

curl 'https://api.bricqs.com/api/v1/contests/active?engagement_id=eng_uuid_456' \
  -H "Authorization: Bearer bq_live_xxxxx"

# Response (200 OK)
{
  "contests": [ { ...active contest row, see data model... } ]
}

Enter a contest

Creates one entry per (contest, participant). Idempotent on the composite: re-entering returns the existing entry with already_entered: true rather than failing.

curl -X POST https://api.bricqs.com/api/v1/contests/ctst_uuid_123/enter \
  -H "Authorization: Bearer bq_live_xxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "participant_id": "user_42",
    "engagement_id": "eng_uuid_456"
  }'

# Response (200 OK)
{
  "success": true,
  "entry_id": "ent_uuid_789",
  "already_entered": false,
  "message": "Entered the contest."
}

Read your standing

Returns the participant’s entry state, current score, rank, and the breakdown of how their score was earned. Use this for the “Your standing” widget alongside the public leaderboard.

curl 'https://api.bricqs.com/api/v1/contests/ctst_uuid_123/me?participant_id=user_42' \
  -H "Authorization: Bearer bq_live_xxxxx"

# Response (200 OK), see the data-model section above

Read the public leaderboard

Returns the top entries (excluding disqualified) plus the participant’s own entry. Excludes participants with no score. Paginates with page.

curl 'https://api.bricqs.com/api/v1/contests/ctst_uuid_123/leaderboard/public?participant_id=user_42&page=1' \
  -H "Authorization: Bearer bq_live_xxxxx"

# Response (200 OK), see the data-model section above

Pattern 1: Weekly quiz contest, ranked top-10 prizes

The most common contest shape. Define scoring rules that award points for quiz completion (with an accuracy multiplier). Set a top-10 prize map. Let the lifecycle worker handle weekly resets by scheduling the next contest for the following week.

{
  "name": "Weekly Quiz Sprint",
  "starts_at": "2026-05-27T00:00:00Z",
  "ends_at":   "2026-06-02T23:59:59Z",
  "completion_type": "ranked",
  "score_config": {
    "scoring_rules": [
      { "fact_name": "behavior.quiz_completed.v1",
        "points": "payload.score",
        "cap_per_occurrence": 100 }
    ]
  },
  "prize_config": [
    { "rank_from": 1,  "rank_to": 1,  "reward": { "type": "voucher", "code": "WK_GOLD" }, "monetary_value": 100 },
    { "rank_from": 2,  "rank_to": 3,  "reward": { "type": "voucher", "code": "WK_SILVER" }, "monetary_value": 50 },
    { "rank_from": 4,  "rank_to": 10, "reward": { "type": "voucher", "code": "WK_BRONZE" }, "monetary_value": 20 }
  ],
  "max_reward_liability": 250,
  "fraud_config": {
    "max_score_per_minute": 100,
    "max_score_per_hour":   400,
    "auto_flag_threshold":  3,
    "auto_disqualify_threshold": 5
  }
}

The total prize liability (100 + 2x50 + 7x20 = 340) exceeds the budget cap (250), so the worker will allocate top winners until the cap is reached and skip the rest. Tune the cap or the prize map together; do not let one outpace the other.

Pattern 2: Raffle weighted by activity score

When the audience is wide and ranked competition is unfair (skilled users would always win), use completion_type: raffle. Every point earned is a ticket; the winner is drawn weighted by score. Casual users still have a chance; power users still get rewarded for activity.

{
  "name": "Activity Raffle",
  "completion_type": "raffle",
  "starts_at": "2026-05-20T00:00:00Z",
  "ends_at":   "2026-05-26T23:59:59Z",
  "score_config": { "source": "points" },
  "prize_config": [
    { "rank_from": 1, "rank_to": 1, "reward": { "type": "coupon", "code": "RAFFLE_WIN" }, "monetary_value": 50 }
  ]
}

Source "points" means every points-awarded fact contributes the delta as score. Pair the raffle with your points economy and the contest needs no per-action rules.

Pattern 3: Cohort-scoped contest for fairness

Global contests reward incumbents. Use the cohort_config field to scope by signup month, region, plan, or team, so a new participant can see a credible path to a top spot.

{
  "name": "May 2026 New-Joiner Sprint",
  "starts_at": "2026-05-27T00:00:00Z",
  "ends_at":   "2026-06-02T23:59:59Z",
  "completion_type": "ranked",
  "cohort_config": {
    "signup_month": "2026-05"
  },
  "score_config": { "source": "points" },
  "prize_config": [
    { "rank_from": 1, "rank_to": 5, "reward": { "type": "voucher", "code": "WELCOME_PRIZE" }, "monetary_value": 25 }
  ]
}

Run cohort-scoped contests alongside a global one. New users see themselves in a fair fight; competitive users still get the global ranks they care about. Most successful consumer programs run both at once.

Pattern 4: Sync prize allocations to your fulfillment system

Until outbound webhook delivery for contest events ships, poll the allocations endpoint (admin scope) once after the contest enters completed status. The list is final; re-running the poll is a no-op.

// Run after the contest's scoring_cutoff_at
const res = await fetch(
  `https://api.bricqs.com/api/v1/contests/${CONTEST_ID}/prizes/allocations`,
  { headers: { Authorization: `Bearer ${process.env.BRICQS_ADMIN_API_KEY}` } }
);
const { allocations } = await res.json();

for (const a of allocations) {
  // a.participant_id, a.rank, a.reward, a.monetary_value, a.code_value
  await fulfillment.shipPrize({
    user_id: a.participant_id,
    sku: a.reward.code,
    voucher: a.code_value,
  });
}

The allocations list is finalised when the contest hits completed status. Re-running this poll is safe (the underlying allocations are append-only and your fulfillment side should be keyed on allocation id). When the webhook delivery channel ships, point the same handler at the event payload.