You render the form. We take the signup.
Waitlist is API-only — there is no hosted page and no embed script. Two anonymous endpoints: read the waitlist, post an entry.
1
Read the waitlist (optional)
Fetch copy and branding at render time so marketing can change the headline without a redeploy. Anonymous — no token, no CORS credentials.
curl 'https://api.waitlist.productcraft.co/v1/waitlists/acme/acme-pro?lang=pt-BR'{
"slug": "acme-pro",
"workspace_slug": "acme",
"canonical_workspace_slug": "acme",
"display_name": "Acme Pro early access",
"description": "Sign up to be among the first to try Acme Pro.",
"status": "active",
"custom_fields": [],
"confirmation_message": "You're on the list. We'll be in touch.",
"recaptcha_site_key": null,
"referral_rewards": { "milestones": [] },
"variant": null,
"brand": {
"brand_name": "Acme",
"brand_logo_url": "https://cdn.acme.com/logo.png",
"primary_color": "#1E40AF"
}
}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.
2
Submit an entry
curl https://api.waitlist.productcraft.co/v1/waitlists/acme/acme-pro/entries \
-H 'content-type: application/json' \
-d '{
"email": "ada@example.com",
"name": "Ada Lovelace",
"interest": "The realtime collaboration bits",
"referrer": "Twitter",
"referral_code": "C67AB5HS",
"metadata": { "company": "Acme Industries", "role": "engineer" }
}'import { Waitlist } from "@productcraft/waitlist";
// The public scope needs no key and never sends one, so it is safe
// in a browser bundle. Both slugs are bound by name.
const form = new Waitlist().public({ workspace: "acme", waitlist: "acme-pro" });
const entry = await form.entries.create({
email: "ada@example.com",
name: "Ada Lovelace",
metadata: { company: "Acme Industries", role: "engineer" },
referral_code: "C67AB5HS",
});
console.log(entry.position, entry.referral_code);On a static page, paste the HTML form from your waitlist's Snippet tab in the console. It posts from the browser with no backend and no API key, shows the person their place in line and a referral link, and explains each error.
<!-- Style the form however you like; keep the name attributes. -->
<form id="waitlist-form">
<input name="name" placeholder="Your name" required>
<input name="email" type="email" placeholder="you@example.com" required>
<button type="submit">Join the waitlist</button>
<p id="waitlist-status" role="status"></p>
</form>
<script>
(function () {
var form = document.getElementById("waitlist-form");
var status = document.getElementById("waitlist-status");
form.addEventListener("submit", function (event) {
event.preventDefault();
var data = new FormData(form);
var ref = new URLSearchParams(window.location.search).get("ref");
status.textContent = "Joining…";
fetch("https://api.waitlist.productcraft.co/v1/waitlists/acme/acme-pro/entries", {
method: "POST",
headers: { "content-type": "application/json" },
body: JSON.stringify({
email: data.get("email"),
name: data.get("name"),
referral_code: ref || undefined
})
})
.then(function (res) {
return res.json().catch(function () { return {}; }).then(function (body) {
if (res.status === 201) {
var share = window.location.origin + window.location.pathname + "?ref=" + body.referral_code;
status.textContent = "You're number " + body.position + " in line. Share " + share + " to move up.";
form.reset();
} else if (res.status === 409) {
status.textContent = "You're already on the list.";
} else if (res.status === 403) {
status.textContent = "This site is not allowed to add sign-ups to this waitlist.";
} else if (res.status === 422) {
status.textContent = "This waitlist is not open for sign-ups right now.";
} else {
status.textContent = "Could not sign you up. Try again.";
}
});
})
.catch(function () {
status.textContent = "Could not reach the waitlist. Check your connection, and that this site is on the waitlist's allowed sites.";
});
});
})();
</script>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:
{
"id": "150489b4-558d-4c2a-93b2-dec1b657558c",
"email": "ada@example.com",
"name": "Ada Lovelace",
"position": 147,
"status": "approved",
"referral_code": "C67AB5HS",
"created_at": "2026-07-28T20:09:16.626Z",
"effective_position": 147
}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.
3
Errors to render
400— validation failed (missingname, malformed email), a disposable-email domain, or a rejected reCAPTCHA token. The body'smessageis 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 theoriginit 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 inaccepting_signupsandsignups_note.429— per-IP, per-waitlist rate limit. The message carries the retry window in seconds.
4
Allow only your own sites (optional)
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.
curl -X PATCH https://api.waitlist.productcraft.co/v1/workspaces/<workspace_id>/waitlists/<waitlist_id> \
-H 'authorization: Bearer pcft_live_...' \
-H 'content-type: application/json' \
-d '{ "allowed_origins": ["https://acme.com", "https://*.acme.com"] }'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.
5
Stop bots with reCAPTCHA, Turnstile or hCaptcha (optional)
Pick one bot check per waitlist: reCAPTCHA v3, Cloudflare Turnstile or hCaptcha. Save its provider and both keys from the provider's dashboard; the secret key is stored encrypted and never returned. The public read returns captcha (provider and site_key) so your form knows which widget to load, and every sign-up sends the widget's token as captcha_token. Send "captcha_provider": null to turn it off.
curl -X PATCH https://api.waitlist.productcraft.co/v1/workspaces/<workspace_id>/waitlists/<waitlist_id> \
-H 'authorization: Bearer pcft_live_...' \
-H 'content-type: application/json' \
-d '{ "settings": { "captcha_provider": "turnstile", "captcha_site_key": "0x4AAAA...", "captcha_secret_key": "0x4AAAA..." } }'<form id="waitlist-form">
<input name="email" type="email" required>
<div class="cf-turnstile" data-sitekey="0x4AAAA..."></div>
<button>Join</button>
</form>
<script src="https://challenges.cloudflare.com/turnstile/v0/api.js" async defer></script>
<script>
document.getElementById('waitlist-form').addEventListener('submit', async (e) => {
e.preventDefault();
const data = new FormData(e.target);
await fetch('https://api.waitlist.productcraft.co/v1/waitlists/acme/acme-pro/entries', {
method: 'POST',
headers: { 'content-type': 'application/json' },
// hCaptcha: the field is "h-captcha-response"
body: JSON.stringify({ email: data.get('email'), captcha_token: data.get('cf-turnstile-response') }),
});
});
</script>A missing or failing token gets 400. reCAPTCHA works as below; waitlists set up with the older recaptcha_site_key and recaptcha_token keep working.
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.
curl -X PATCH https://api.waitlist.productcraft.co/v1/workspaces/<workspace_id>/waitlists/<waitlist_id> \
-H 'authorization: Bearer pcft_live_...' \
-H 'content-type: application/json' \
-d '{ "settings": { "recaptcha_site_key": "6Lc...", "recaptcha_secret_key": "6Lc..." } }'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.
// <script src="https://www.google.com/recaptcha/api.js?render=6Lc..."></script>
grecaptcha.ready(async () => {
const token = await grecaptcha.execute('6Lc...', { action: 'waitlist_signup' });
await fetch('https://api.waitlist.productcraft.co/v1/waitlists/acme/acme-pro/entries', {
method: 'POST',
headers: { 'content-type': 'application/json' },
body: JSON.stringify({ email, name, recaptcha_token: token }),
});
});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.
6
Ask sign-ups to confirm their email (optional)
Turn on email_confirmation and every new sign-up comes back unconfirmed and gets one email with a confirmation link. Until its owner clicks it, the sign-up has no place in line, earns its referrer nothing, is not on the leaderboard and fires no webhook. That stops people (and bots) signing up addresses that are not theirs, and it gives you a record that each address agreed to join.
curl -X PATCH https://api.waitlist.productcraft.co/v1/workspaces/<workspace_id>/waitlists/<waitlist_id> \
-H 'authorization: Bearer pcft_live_...' \
-H 'content-type: application/json' \
-d '{ "settings": { "email_confirmation": true, "confirmation_expiry_days": 7 } }'- The email uses your workspace's Confirm email template in Mail (Waitlist creates
waitlist-confirmfor you). Its link opens a page on productcraft.co with your logo and colour; the visitor presses Confirm my spot. A button rather than the link itself, because mail scanners open links in emails. - Confirming moves the sign-up to
approved(orpendingwhen you approve by hand), credits the referrer, firesentry.createdand sends the welcome email. - Sign-ups nobody confirms are deleted after
confirmation_expiry_days(1–30, default 7). - An address gets at most one confirmation email from your workspace, and three from all of ProductCraft, in any 24 hours, however many times it is entered. A bot typing a stranger's address into forms cannot use us to flood their inbox.
- The public read returns
email_confirmation, so your form can say “Check your inbox” instead of “You're on the list”. A visitor who lost the email can ask for it again withPOST …/entries/resend-confirmation; it answers202whether or not the address signed up.
7
Referral fraud checks and the review queue (optional)
A leaderboard with prizes gets gamed. Set fraud_protection to relaxed, balanced or strict (default off). From then on aliases of one mailbox (ada+win@, a.da@gmail.com) are one contact, so a second one gets 409, and a sign-up that looks like abuse is held.
- Relaxed holds clear abuse: referring yourself, a referral from the referrer's own device and network, or 30+ sign-ups an hour from one network.
- Balanced also holds a referral from the referrer's device or network, 10+ sign-ups an hour per network and 5+ a day per device.
- Strict holds at 3 an hour per network and 2 a day per device, and any referral from a referrer that is held or unconfirmed.
Networks and devices are compared as salted hashes; the raw IP and browser signature are never stored. Send a stable device_id from your form (a random id in localStorage) for better device grouping.
A held sign-up has no place in line, earns its referrer nothing, is not on the leaderboard and gets no email or webhook. To the visitor it looks like pending. Review it under the waitlist's Review tab in the console, where each one lists why it was held, or through the API: POST …/entries/:id/release lets it carry on as if the checks had passed; PATCH …/entries/:id with rejected turns it away and sends nothing.
8
Entrant status page
Every sign-up gets a private link in its emails (the confirmation email, and the welcome email as {{statusUrl}}) to a page with its place in line, its referral link and count, and its progress to your rewards. Coming back to check is what gets people sharing. The link carries a signed token; there is no lookup by email address, so nobody can find out who signed up.
- Hosted:
productcraft.co/w/<workspace>/<waitlist>/status?token=…with your logo and colour. Nothing to build. - Your own page: set
status_page_url. The emails link there with?token=…and the hosted page redirects there. Embed the widget, or read the entry yourself. - Set
signup_page_urlto the page with your form, so each entrant's referral link is that page with?ref=<code>.
<iframe id="waitlist-status" title="Your place in line"
style="width:100%;max-width:420px;height:420px;border:0"></iframe>
<script>
var token = new URLSearchParams(location.search).get('token');
document.getElementById('waitlist-status').src =
'https://productcraft.co/w/acme/acme-pro/status/embed?token=' + encodeURIComponent(token || '');
</script>curl 'https://api.waitlist.productcraft.co/v1/waitlists/acme/acme-pro/entries/me?token=<token>'
{
"status": "approved",
"rank": 12,
"referral_code": "464QTHE0",
"referral_link": "https://acme.com/early-access?ref=464QTHE0",
"referral_count": 2,
"referral_boost": 5,
"rewards": {
"milestones": [{ "count": 3, "reward": "Skip the line", "reached": false }],
"next": { "count": 3, "reward": "Skip the line", "remaining": 1 }
},
"waitlist_name": "Acme Pro",
"confirmed_at": "2026-11-18T09:12:00.000Z",
"status_url": "https://productcraft.co/w/acme/acme-pro/status?token=…",
"status_page_url": null
}A token that is not valid, or belongs to a sign-up that was deleted, gets 404 ENTRY_LINK_INVALID. Treat the link like a password: whoever has it sees that sign-up (never anyone else's).
9
Test it before you launch
Add a test sign-up to see the entry, the welcome email and your webhooks work — even while the waitlist is still a draft.
curl -X POST https://api.waitlist.productcraft.co/v1/workspaces/<workspace_id>/waitlists/<waitlist_id>/test-entries \
-H 'authorization: Bearer pcft_live_...' \
-H 'content-type: application/json' \
-d '{ "trigger_webhooks": true, "send_welcome_email": true }'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.
10
Leaderboard
Anonymous top-referrer ranking — the “skip the line” mechanic from chapter 5. Same access rule as the public info endpoint (active waitlists only).
curl 'https://api.waitlist.productcraft.co/v1/waitlists/acme/acme-pro/leaderboard?limit=10'[
{ "position": 1, "referral_count": 42, "masked_email": "a***@example.com" },
{ "position": 2, "referral_count": 31, "masked_email": "b***@acme.org" }
]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.