Referral System

How the viral referral loop works — tokens, tracking, and leaderboards.

How It Works

Every signup on MakeEmWait gets a unique referral token. When they share their referral link and someone signs up through it, the referrer gets credit. This creates a viral loop where your users actively promote your waitlist.

The Viral Loop

1. Person A signs up and gets a referral link
2. Person A shares the link with friends
3. Person B clicks the link and signs up
4. Person A gets referral credit and moves up on the waitlist (by 1 position by default, or more if referral boost is configured)
5. Person B also gets their own referral link and the cycle repeats

Referral Tokens

Each signup receives a unique 32-character hex referral token generated via crypto.randomBytes(16).toString('hex'), producing a 128-bit random value (e.g., a3b2c1d4e5f67890a1b2c3d4e5f67890). The token is used to build referral links:

https://makeemwait.com/waitlist.html?id=WAITLIST_ID&ref=REFERRAL_TOKEN

When someone signs up with a referred_by_token, the system:

1. Validates the referral token — looks up the referrer and checks for self-referral (the referral token must not belong to the same email as the new signup)
2. Increments the referrer’s referral_count
3. Boosts the referrer’s position using the formula: new_position = max(1, current_position - referral_boost)
4. Updates their leaderboard position

All of these steps happen atomically in a single database transaction. The referral count increment and position adjustment are bundled into one transaction, preventing race conditions where two simultaneous referrals could produce inconsistent results.

Self-Referral Prevention

The system prevents users from referring themselves. When a signup includes a referred_by_token, the system resolves the token to find the referrer’s email. If the referrer’s email matches the new signup’s email, the referral is silently ignored — the signup still succeeds, but no referral credit is awarded and no position boost is applied.

Leaderboard

The leaderboard shows the top referrers for a waitlist, ranked by referral count. It’s fully anonymized — only first name initial and last initial are shown (e.g., “J.D.”), so no full names, emails, or other identifying information are exposed.

How the Leaderboard Works Internally

The leaderboard is powered by an optimized database index. Each signup’s referral count is stored in a way that enables efficient descending-order lookups, so fetching the top referrers is a single fast query rather than scanning and sorting all records.

How It’s Displayed

On the success page (/success.html), two API calls power the referral experience:

1. Live signup status — GET /public/waitlists/{id}/signups/{email} fetches the user’s current position, total signups, and referral count in real time.
2. Leaderboard — GET /public/waitlists/{id}/leaderboard?limit=1 fetches the top referrer’s count, displayed as a motivational target: “The #1 referrer has 23. Can you beat them?”

This encourages sharing without revealing anyone’s identity.

Public Endpoint

GET /public/waitlists/{waitlist_id}/leaderboard?limit=10

Parameters:

Response:

{
  "waitlist_id": "a1b2c3d4",
  "leaderboard": [
    {
      "rank": 1,
      "referral_count": 12
    },
    {
      "rank": 2,
      "referral_count": 8
    }
  ]
}

Configurable Referral Boost

By default, each referral moves the referrer up by 1 position. You can increase this to reward sharing more aggressively.

Set the referral_boost value in your waitlist settings to control how many positions each referral is worth. For example, with referral_boost: 5, each successful referral moves the referrer up 5 positions.

The Boost Formula

When a referral is credited, the referrer’s position is recalculated using this formula:

new_position = max(1, current_position - referral_boost)

The max(1, ...) ensures a referrer’s position never goes below 1 (the top of the waitlist). For example, if a referrer is at position 15 and the waitlist’s referral_boost is set to 5, they move to position 10. If they are already at position 3 with a boost of 5, they move to position 1 (not -2).

This position adjustment is performed atomically in a database transaction — the referral count increment and the position update happen together in a single transaction, so there is no window where the data could be inconsistent.

Available on all plans.

Referral Notification Emails (Pro)

When enabled, referrers receive an email every time someone signs up through their referral link. The email includes their new position and encourages them to keep sharing.

Enable this with the notify_referrer setting in your waitlist settings. Notifications are rate-limited to one email per referrer per hour to avoid spamming active referrers.

Referral Milestones

Referral milestones let you automatically email referrers when they hit specific referral counts (e.g., 5, 10, 25, 50). This rewards your most active promoters and encourages continued sharing.

Setup

1. Create a referral_milestone email template with your congratulations message
2. Assign the template to your waitlist under Edit > Email Templates
3. Set your milestone thresholds under Edit > Advanced Settings > Referral milestones (comma-separated numbers, e.g., 5, 10, 25, 50, 100)

When a referrer’s count reaches one of your configured thresholds, the milestone email is sent automatically.

Available Template Variables

Referral Webhooks

If you have webhooks configured with the referral.credited event, a webhook fires every time a referral is recorded:

{
  "event": "referral.credited",
  "waitlist_id": "a1b2c3d4",
  "data": {
    "email": "jane@example.com",
    "referral_count": 12,
    "position": 3
  },
  "timestamp": "2025-03-15T10:30:00.000Z"
}

Vanity Referral Codes (Advanced+)

By default, referral tokens are 32-character hex strings (e.g., a3b2c1d4e5f67890a1b2c3d4e5f67890). Vanity referral codes give your users human-readable codes like blue-tiger-42 that are easier to share verbally and in text.

Enabling Vanity Codes

Enable vanity codes on your waitlist:

PATCH /waitlists/{waitlist_id}
{
  "settings": {
    "vanity_referral_codes": true
  }
}

How Codes Are Generated

When vanity codes are enabled, each signup receives a vanity code in addition to their standard hex token. The code is randomly generated in adjective-noun-number format (e.g., swift-arrow-07, golden-reef-53). The word lists contain 200+ adjectives and 200+ nouns, combined with a two-digit number, giving millions of possible combinations.

Both the hex token and the vanity code work for referral lookups. Referral links can use either:

https://makeemwait.com/waitlist.html?id=WAITLIST_ID&ref=blue-tiger-42
https://makeemwait.com/waitlist.html?id=WAITLIST_ID&ref=a3b2c1d4e5f67890a1b2c3d4e5f67890

The vanity code is included in the signup response and on the success page, making it easy for users to share their personal referral code.

SMS Notifications (Pro)

In addition to email notifications, you can enable SMS notifications for referral events. When someone signs up through a referrer’s link, the referrer receives a text message notifying them of the new referral and their updated position.

Enable SMS notifications in your waitlist settings:

PATCH /waitlists/{waitlist_id}
{
  "settings": {
    "sms_notify_referrer": true
  }
}

SMS notifications are sent alongside email notifications (if both are enabled). They follow the same rate limiting as email notifications — one notification per referrer per hour.

API Integration

Create a Signup with Referral

When integrating via the API, include the referred_by_token in the signup request:

POST /public/waitlists/{waitlist_id}/signups
{
  "email": "newuser@example.com",
  "referred_by_token": "a3b2c1d4e5f67890a1b2c3d4e5f67890"
}

Check a Signup’s Referral Count

GET /public/waitlists/{waitlist_id}/signups/{email}

The response includes referral_count and the signup’s current position. Note that the referral_token is only returned in the initial POST /signups response, not in GET requests.

Related

• Signup Form — how referral links are passed through the signup flow
• Managing Signups — view referral data per signup and export to CSV
• Analytics — track referral signups and top referrers over time (Pro)