Recruitment Referral
Data Entity
Description
A referral token record created when a peer mentor shares a membership recruitment link. Tracks the referring peer mentor, the unique token, and conversion outcomes when referred users complete registration. Powers HLF's membership recruitment feature where the app serves as a membership benefit.
Data Structure
| Name | Type | Description | Constraints |
|---|---|---|---|
id |
uuid |
Primary key. Globally unique identifier for the referral record. | PKrequiredunique |
referrer_id |
uuid |
Foreign key to the users table. Identifies the peer mentor who generated and shared the referral link. | required |
organization_id |
uuid |
Foreign key to the organizations table. Scopes the referral to a specific organization so conversion tracking and analytics remain tenant-isolated. | required |
token |
string |
Cryptographically random, URL-safe token that uniquely identifies this referral. Embedded in the shareable deep link. Generated by Referral Link Infrastructure using a CSPRNG with at least 128 bits of entropy. | requiredunique |
status |
enum |
Lifecycle state of the referral token. Controls whether the token is still redeemable and how it appears in analytics. | required |
converted_user_id |
uuid |
Foreign key to the users table for the newly registered user who redeemed this referral. NULL until a successful conversion occurs. Set exactly once; subsequent writes are rejected. | unique |
expires_at |
datetime |
UTC timestamp after which the token is no longer redeemable. Defaults to 30 days after creation. Configurable at the organization level via settings. The scheduled expiry job sets status to 'expired' when this threshold is crossed. | required |
created_at |
datetime |
UTC timestamp when the referral record was created and the token was issued. | required |
converted_at |
datetime |
UTC timestamp when the referred user completed registration and the referral was marked as converted. NULL until conversion. Must be >= created_at and <= expires_at. | - |
share_count |
integer |
Number of times the referral deep link has been opened or resolved (click count). Incremented by the Referral Link Infrastructure on each deep link resolution event. Used for analytics on referral reach vs. conversion rate. | required |
metadata |
json |
Optional JSON bag for extensible tracking context. May include the share channel (e.g., 'native_share_sheet', 'copy_link'), device platform, or campaign tag set at link creation time. Stored as JSONB for indexed querying. | - |
Database Indexes
idx_recruitment_referral_token
Columns: token
idx_recruitment_referral_referrer_id
Columns: referrer_id
idx_recruitment_referral_organization_id
Columns: organization_id
idx_recruitment_referral_status
Columns: status
idx_recruitment_referral_converted_user_id
Columns: converted_user_id
idx_recruitment_referral_referrer_status
Columns: referrer_id, status
idx_recruitment_referral_org_created_at
Columns: organization_id, created_at
idx_recruitment_referral_expires_at
Columns: expires_at
Validation Rules
token_format_validation
error
Validation failed
expires_at_must_be_future
error
Validation failed
converted_at_within_validity_window
error
Validation failed
referrer_id_references_existing_user
error
Validation failed
organization_id_references_existing_org
error
Validation failed
converted_user_id_uniqueness
error
Validation failed
share_count_non_negative
error
Validation failed
metadata_schema_validation
warning
Validation failed
Business Rules
unique_token_per_referral
Every referral record must carry a globally unique, cryptographically random token. The token is generated by Referral Link Infrastructure using a CSPRNG and stored with a UNIQUE constraint. Duplicate tokens are rejected at the database level before a response is returned.
single_conversion_per_token
A referral token may be redeemed by exactly one new user. Once converted_user_id is set and status transitions to 'converted', all subsequent redemption attempts for the same token are rejected with a 409 Conflict response.
no_self_referral_conversion
The user completing registration via a referral link (converted_user_id) must be different from the peer mentor who created the referral (referrer_id). Self-redemption is rejected to prevent artificial inflation of conversion metrics.
token_expiry_enforcement
Referral tokens become non-redeemable after expires_at. Recruitment Service checks the expiry timestamp before allowing conversion. A scheduled job (implemented within Recruitment Service or a cron-triggered Next.js route) scans for pending tokens past their expires_at and transitions their status to 'expired'.
organization_scoped_referral
A referral's organization_id must match the referring peer mentor's primary organization. This ensures conversion analytics, reporting, and deep link routing are all correctly tenant-isolated. The Recruitment Service resolves the organization from the authenticated user's JWT claims at token generation time.
referrer_must_be_active_peer_mentor
Only users holding an active Peer Mentor role in the specified organization may generate referral tokens. Users who are deactivated, paused, or hold only Coordinator/Admin roles are rejected. Role validation is performed via Auth Middleware before the token generation endpoint is reached.
immutable_converted_referral
Once a referral record reaches 'converted' status, its referrer_id, organization_id, token, converted_user_id, and converted_at fields are immutable. Only metadata and share_count may be updated post-conversion for analytics enrichment.
CRUD Operations
Storage Configuration
Entity Relationships
A user (peer mentor) generates referral tokens and has their conversion outcomes tracked