Referral Invite
Data Entity
Description
Tracks personalized invite links and QR codes generated by peer mentors and coordinators for recruiting new members, capturing creation, sharing, and conversion lifecycle for the referral program.
Data Structure
| Name | Type | Description | Constraints |
|---|---|---|---|
id |
uuid |
Primary key | PKrequiredunique |
organization_id |
uuid |
Organization this invite belongs to (tenant isolation) | required |
created_by_user_id |
uuid |
User (peer mentor or coordinator) who generated the invite | required |
invite_code |
string |
Unique short code embedded in the invite link and QR code | requiredunique |
invite_url |
string |
Full deep-link URL containing the invite_code | requiredunique |
qr_code_url |
string |
URL or path to the generated QR code image for this invite | - |
channel |
enum |
How the invite was shared | - |
status |
enum |
Lifecycle state of the invite | required |
expires_at |
datetime |
When this invite link expires; null means no expiry | - |
max_uses |
integer |
Maximum number of times this invite can be redeemed; null means unlimited | - |
use_count |
integer |
How many times this invite has been redeemed | required |
converted_user_id |
uuid |
User account created as a result of this invite (populated on conversion) | - |
converted_at |
datetime |
Timestamp when the invite was successfully converted to a new user registration | - |
note |
text |
Optional free-text note by the inviter (e.g. context about the recruit) | - |
created_at |
datetime |
Record creation timestamp | required |
updated_at |
datetime |
Last modification timestamp | required |
Database Indexes
idx_referral_invites_invite_code
Columns: invite_code
idx_referral_invites_created_by_user_id
Columns: created_by_user_id
idx_referral_invites_organization_id
Columns: organization_id
idx_referral_invites_status
Columns: status
idx_referral_invites_org_status
Columns: organization_id, status
idx_referral_invites_expires_at
Columns: expires_at
Validation Rules
invite_code_format
error
Validation failed
invite_url_valid
error
Validation failed
expires_at_future
error
Validation failed
max_uses_positive
error
Validation failed
use_count_not_negative
error
Validation failed
converted_fields_paired
error
Validation failed
Business Rules
invite_code_globally_unique
Each invite_code must be unique across all organizations to ensure deep-link routing is unambiguous
auto_expire_on_max_uses
When use_count reaches max_uses, status is automatically set to 'converted' or 'expired' and further redemptions are rejected
expired_invites_not_redeemable
Invites with expires_at in the past or status != 'active' must be rejected at redemption time
tenant_isolation
Invite links may only be redeemed within the same organization they were created for; cross-org redemption is rejected
conversion_is_final
Once converted_at is set and converted_user_id is populated, the record is immutable except for audit fields
revocation_clears_qr
When an invite is revoked, qr_code_url should be treated as invalid; the QR code widget must verify status before rendering