Concepts
Projects, keys, waitlists, signups, position, referrals and double opt-in.
Project
The unit of ownership. A project holds API keys, waitlists, webhook endpoints
and a plan. Everything you can call is scoped to the project of the key you
used; another project's ids answer 404.
API keys
| Key | Format | Where | Can |
|---|---|---|---|
| Secret | gw_sk_... | Servers only | Every route |
| Publishable | gw_pk_... | Browsers and pages | Join, look up status, leaderboard |
A project has a list of allowed origins; its publishable keys are only
accepted from a browser request whose Origin exactly matches an entry (no wildcards).
Keys are shown once when created; only a hash is stored. Revoke from the
dashboard.
Waitlist
A named list inside a project, with its own settings: referrals, double opt-in, captcha, redirect URL and allowlist, leaderboard, and the postal address printed in email footers. Free projects can have 2 waitlists of up to 1,000 live signups each (plan limits).
Settings and name can be changed at any time (PATCH /waitlists/:id or the
dashboard); the slug cannot. A waitlist can be archived: it stops accepting
joins but stays readable and exportable, and can be restored.
See Waitlists.
Signup
One email address on one waitlist. Fields you will meet: id (UUIDv7),
email, status, referralCode, position, source (UTM tags and
referrer), createdAt.
Status
| Status | Meaning |
|---|---|
pending | Joined, email not confirmed yet |
verified | Clicked the confirmation link (or double opt-in is off) |
removed | Erased by you or by the person; kept only as an anonymous tombstone |
Idempotent by email. Joining twice with the same address returns the
existing signup (200, created: false) and never makes a second row.
Addresses are normalized first, so A.b+promo@gmail.com and ab@gmail.com
are the same person. Retrying is always safe.
Position
Your 1-based rank among live signups, ordered by join time. It is computed
when asked and never stored, so it stays right when people ahead of you leave
or when referrals move you up. A removed signup has position: null.
Referrals
Every signup gets an 8-character referralCode. Someone who joins with
ref: <code> is the referrer's referral.
- The referral starts
pending. - It becomes converted only when the new person confirms their email, so typing a friend's email gets nobody ahead.
- Each converted referral moves the referrer up
positions_per_referralplaces (default 1; cap withmax_bumps). - Self-referrals, addresses already on the list, unverified referrers and same-network joins are recorded but earn nothing.
Share links look like https://yoursite.com/?ref=YUJZ6KTD; read the code with
useReferralFromUrl() (opt-in, memory-only by default) or from the query
string yourself. The leaderboard ranks signups by converted referrals;
names are hidden by default (Anonymous #3).
Double opt-in
On by default. A join stores the address as pending and queues a
confirmation email with a single-use link valid for 48 hours. Opening it makes
the signup verified, sends a welcome email, converts any pending referral,
and redirects to your redirect_url (if it matches your allowlist) or to a
plain confirmation page. Turn it off per waitlist with
settings.double_opt_in: false: signups are then verified on join.
Why keep it on: it keeps typos and other people's addresses off your list, protects your sending reputation, and is what makes referral counts trustworthy.
Events
Three webhook events describe a signup's life: signup.created,
signup.verified, referral.converted. See Webhooks.