Referrals API

Both-sided referral flows: a participant generates a code, a friend validates and converts it, and both sides are credited exactly once.

Auth

All endpoints require an X-API-Key header. Production keys are prefixed bq_live_; sandbox keys bq_test_.

Scopes

Participant key Generate requires write:events (participant JWT, pinned to its own identity) or an API key with events:write (mint default). Validate is public; convert is conditional (JWT verified when present, required for gated engagements). stats/me requires read:state (JWT, own stats) or gamify:read (API key).

Admin scope GET /gamify/referrals/stats/{participant_id} (stats for an arbitrary participant) is a dashboard-session endpoint, not an API-key route.

Base URLhttps://api.bricqs.co/api/v1/gamify

Endpoint inventory

Method	Endpoint	Auth	Purpose
POST	`/gamify/referrals/generate`	JWT (write:events) or API key	Generate (or return the existing) code + share URL for the participant.
GET	`/gamify/referrals/validate/{code}`	Public	Check a code before signup UX; gated engagements enforce auth.
POST	`/gamify/referrals/convert`	Conditional	Record a conversion. Atomic at the database (one credit per conversion; safe under retries and double-clicks). Fires `referral.converted.v1`.
GET	`/gamify/referrals/stats/me`	JWT (read:state) or API key (gamify:read)	Own referral stats (conversions, credits).
GET	`/gamify/referrals/stats/{participant_id}`	Dashboard session	Arbitrary participant stats (operator surface).

The flow

# 1. Referrer (browser, participant JWT) generates their code
POST /api/v1/gamify/referrals/generate
Authorization: Bearer <participant-jwt>

# 2. Friend's client validates before rendering signup UX
GET /api/v1/gamify/referrals/validate/REF_CODE

# 3. On the friend's qualifying action, record the conversion
POST /api/v1/gamify/referrals/convert
{ "referral_code": "REF_CODE", "referee_participant_id": "friend_user_id" }

# Both sides are credited once; referral.code_generated.v1 and
# referral.converted.v1 webhooks fire for your backend.

Known limitation: there is no configurable attribution window today; conversions attribute to the code whenever they are recorded. If your program needs windowing, enforce it in your backend before calling convert.

Errors

Status	Code	When it fires
401	AUTH_UNAUTHENTICATED	Generate without any credential, or convert on a gated engagement without a JWT.
404	not_found	Referral code unknown or inactive.

React SDK

useReferral →

Hook signatures, props, auto-refresh behaviour.

← Back to Gamification API