Referral Links
Data Entity
Description
Stores personalized referral links generated by peer mentors and coordinators for recruiting new members to their organization. Each link contains a signed token tied to the referring user, enabling attribution tracking when new users register through the link.
Data Structure
| Name | Type | Description | Constraints |
|---|---|---|---|
id |
uuid |
Unique identifier for the referral link record | PKrequiredunique |
user_id |
uuid |
Foreign key to the user who generated this referral link (the referrer) | required |
organization_id |
uuid |
Foreign key to the organization the referrer belongs to, scoping the referral to a specific tenant | required |
referral_token |
string |
Cryptographically signed unique token embedded in the referral URL for secure attribution. URL-safe base64 encoded. | requiredunique |
referral_url |
string |
Full deep link URL containing the referral token, used for sharing via messaging apps, QR codes, and social media | requiredunique |
status |
enum |
Current lifecycle state of the referral link | required |
expires_at |
datetime |
Timestamp when the referral link becomes invalid. Null means no expiration. | - |
max_uses |
integer |
Maximum number of successful conversions allowed through this link. Null means unlimited. | - |
use_count |
integer |
Running count of successful conversions (account creations) attributed to this link | required |
click_count |
integer |
Total number of times the referral link has been clicked or scanned, regardless of conversion | required |
campaign_tag |
string |
Optional tag for grouping referral links by campaign or recruitment drive for analytics | - |
share_channel |
enum |
Last known sharing channel used to distribute this link, for analytics purposes | - |
created_at |
datetime |
Timestamp when the referral link was generated | required |
updated_at |
datetime |
Timestamp of the last modification to the referral link record | required |
Database Indexes
idx_referral_links_user_id
Columns: user_id
idx_referral_links_organization_id
Columns: organization_id
idx_referral_links_referral_token
Columns: referral_token
idx_referral_links_status_expires
Columns: status, expires_at
idx_referral_links_user_org_status
Columns: user_id, organization_id, status
idx_referral_links_campaign_tag
Columns: campaign_tag
Validation Rules
valid_referral_token_format
error
Validation failed
valid_referral_url
error
Validation failed
user_exists_and_active
error
Validation failed
organization_exists
error
Validation failed
expires_at_future_date
error
Validation failed
use_count_not_exceeds_max
error
Validation failed
status_transition_valid
error
Validation failed
counts_non_negative
error
Validation failed
Business Rules
one_active_link_per_user_per_org
Each user may have at most one active referral link per organization at any time. Generating a new link revokes the previous active link.
expired_links_reject_conversions
A referral link with status 'expired' or past its expires_at timestamp must not attribute new conversions. Click tracking may still increment but conversion must be rejected.
max_uses_enforcement
When use_count reaches max_uses, the link status transitions to 'expired' and no further conversions are attributed.
revoked_links_non_restorable
A revoked referral link cannot be reactivated. The user must generate a new link instead.
organization_scoped_referrals
A referral link can only recruit new members into the same organization as the referrer. Cross-organization referrals are not permitted.
self_referral_prevention
A user cannot convert their own referral link. The system must reject conversions where the new user's identity matches the referrer.
token_cryptographic_signing
Referral tokens must be cryptographically signed using HMAC-SHA256 with a server-side secret to prevent forgery and tampering.
click_count_increment_idempotent
Click counting should deduplicate rapid repeated clicks from the same device within a short time window (e.g., 5 seconds) to avoid inflated metrics.