POST /referrals/apply-code
Attach a referrer to this user by their referral code. The referrer's code must have been activated (24h cooldown).
The first referrer applied is locked permanently. The active referrer can be reassigned unless it is marked permanent.
Use case
End-user signup flow — apply a referral code you captured from a UTM param, affiliate link, or manual input.
Body
| Field | Type | Required | Description |
|---|---|---|---|
sReferralCode | string | yes | 1–64 chars. Matched case-insensitively. |
Response 200
{
"message": "referral code applied",
"iReferredBy": "…",
"iFirstReferredBy": "…",
"dReferredAt": "2026-04-20T10:00:00.000Z"
}
| Field | Description |
|---|---|
iFirstReferredBy | The original referrer — immutable after first apply. |
Re-applying the same code is a no-op and returns the current state
with message: "referrer already applied".
Errors
| Status | Meaning |
|---|---|
400 | Attempting to self-refer. |
403 | User's current referrer is permanent and cannot be overridden. |
404 | Code not found or still within the 24h activation cooldown. |
Example
curl -X POST "$BASE_URL/referrals/apply-code" \
-H "Authorization: Bearer $ACCESS" \
-H "x-user-id: $USER_ID" \
-H "Content-Type: application/json" \
-d '{ "sReferralCode": "ABCDEF" }'