Referrals API
Generate unique referral codes, validate referral links, process conversions, and retrieve referral statistics.
Authentication: Mixed. Code generation and stats require an
X-API-Key header. Validation and conversion are public endpoints.Endpoints
| Method | Endpoint | Auth | Description |
|---|---|---|---|
| POST | /referrals/generate | API Key | Generate a referral code |
| GET | /referrals/validate/{code} | Public | Validate a referral code |
| POST | /referrals/convert | Public | Convert a referral |
| GET | /referrals/stats/{participant_id} | API Key | Get referral statistics |
Generate Referral Code
Creates a unique referral code for a participant. If the participant already has a code for the given campaign, the existing code is returned.
curl -X POST https://YOUR_API_DOMAIN/api/v1/referrals/generate \
-H "X-API-Key: bq_live_your_key" \
-H "Content-Type: application/json" \
-d '{
"participant_id": "user_123",
"campaign_id": "550e8400-e29b-41d4-a716-446655440000"
}'Response
{
"code": "ALEX2026",
"referral_url": "https://your-campaign.example.com?ref=ALEX2026",
"participant_id": "user_123",
"created_at": "2026-04-10T14:30:00Z"
}Validate Referral Code
Checks whether a referral code is valid and returns the referrer information.
curl -X GET "https://YOUR_API_DOMAIN/api/v1/referrals/validate/ALEX2026"Response
{
"valid": true,
"code": "ALEX2026",
"referrer_id": "user_123",
"campaign_id": "550e8400-e29b-41d4-a716-446655440000"
}Convert Referral
Records a successful referral conversion. Triggers milestone evaluation for the referrer (e.g., "Refer 5 friends" badge).
curl -X POST https://YOUR_API_DOMAIN/api/v1/referrals/convert \
-H "Content-Type: application/json" \
-d '{
"code": "ALEX2026",
"referred_session_id": "sess_newuser_456"
}'Response
{
"converted": true,
"referrer_id": "user_123",
"conversion_id": "conv_789"
}Get Referral Stats
Returns referral statistics for a participant, including total referrals, conversions, and pending invites.
curl -X GET "https://YOUR_API_DOMAIN/api/v1/referrals/stats/user_123" \
-H "X-API-Key: bq_live_your_key"Response
{
"participant_id": "user_123",
"total_referrals": 12,
"conversions": 8,
"pending": 4,
"referral_code": "ALEX2026"
}