You render the form. We take the signup.

Fetch copy and branding at render time so marketing can change the headline without a redeploy. Anonymous — no token, no CORS credentials.

404 means “not found or not active” — a draft, paused or closed waitlist looks identical to a missing one from the outside.

?lang= (BCP-47) beats the Accept-Language header when picking which variant's copy to serve. When a variant is active, variant carries { id, locale, kind } — echo that id back as variant_id on submit so the entry is attributed. See chapter 5.

canonical_workspace_slug is there so a link built against a renamed workspace slug can 301 itself: compare it to the slug in your URL.

email and name are both required. Everything else is optional: interest (free text), referrer (how they heard about you), referral_code (another entry's code — credits that entry), variant_id, recaptcha_token, and metadata — a free-form object for whatever else your form collects. There is no server-side field schema to register first; put your extra inputs in metadata and they come back on the entry.

Response:

referral_code is this signup's code to share. Waitlist doesn't host a page, so build the share link yourself against your own form URL — https://acme.com/join?ref=C67AB5HS — and pass the value straight back as referral_code on the next submission.

status is approved on a waitlist that doesn't require manual review, otherwise pending. position is the immutable join order — it is never renumbered, including when earlier entries are deleted. Render position; effective_position is a forward-compatible mirror of it.

• 400 — validation failed (missing name, malformed email), a disposable-email domain, or a rejected reCAPTCHA token. The body's message is an array of per-field messages you can map onto inputs.
• 403 ORIGIN_NOT_ALLOWED — the page that sent the request is not on the waitlist's allowed origins (section 4). The body names the origin it saw.
• 404 — waitlist not found or not active.
• 409 This email is already on this waitlist — the friendliest handling is “you're already in”, since positions are never disclosed anonymously for an existing email.
• 422 Waitlist is not accepting entries — the list is a draft, paused, closed or full. A new waitlist is a draft unless you create it with "status": "active"; every waitlist response says so in accepting_signups and signups_note.
• 429 — per-IP, per-waitlist rate limit. The message carries the retry window in seconds.

By default any site can post to your waitlist. To accept sign-ups only from your own pages, give the waitlist a list of origins — scheme and host, no path. https://*.acme.com covers every subdomain (handy for preview deployments). An empty list means any site again.

A browser on any other site gets 403 on the CORS preflight and on the post itself, so the form fails loudly instead of silently. Requests from your own server carry no Origin header and are not checked. You can also set allowed_origins when you create the waitlist.

Create a reCAPTCHA v3 key in Google's reCAPTCHA admin console and save both keys it shows you on the waitlist: in the console under the waitlist's Settings, or through the API. The secret key is stored encrypted and never returned; the waitlist only reports recaptcha_secret_configured: true. Send "recaptcha_site_key": null to turn it off again.

From then on every sign-up needs a token. Load reCAPTCHA with your site key, create a token with the action waitlist_signup just before you post, and send it as recaptcha_token. A missing or failing token gets 400 reCAPTCHA verification failed.

The public read in section 1 returns recaptcha_site_key, so your form can load reCAPTCHA only when it is on. The ready-made snippets in the console's “Get the snippet” send the token for you once reCAPTCHA is on: copy them again after you save the keys.

Add a test sign-up to see the entry, the welcome email and your webhooks work — even while the waitlist is still a draft.

The entry gets a test address at Amazon's mailbox simulator, so no real inbox is emailed, and is_test: true. It shows in your entries list but never takes a place in the queue (its position is negative) and is left out of counts, analytics and exports unless you pass include_test=true. Webhooks and the welcome email only go out when you ask, as above. Delete it like any other entry.

Anonymous top-referrer ranking — the “skip the line” mechanic from chapter 5. Same access rule as the public info endpoint (active waitlists only).

A bare array, not an envelope. Emails are masked and only entries with at least one referral appear. limit is 1–50, default 50. Unmasked referrer data is admin-only, on GET .../analytics.