/v1/waitlists/{workspace_slug}/{waitlist_slug}/entriesSubmit a new entry to a public waitlist
The sign-up your form posts. No API key, callable from a browser; a waitlist with `allowed_origins` only accepts browsers on those origins. When the waitlist has a reCAPTCHA site key, send a `recaptcha_token`. Values for custom fields go in `metadata`; `variant_id` from the info read attributes the sign-up to a variant, and `referral_code` credits the referrer.
Path parameters
workspace_slug*stringSlug of the workspace that owns the waitlist (a renamed workspace's old slug still resolves).
waitlist_slug*stringSlug of the waitlist within its workspace.
Headers
Idempotency-KeystringIdempotency key (24 h). A retry with the same key and body returns the first sign-up instead of a 409 `Email already on this waitlist`. Keys are scoped to this waitlist.
Request body
email*stringEmail address
Example: "ada@example.com"
name*stringFull name
Example: "Ada Lovelace"
intereststringFree-text product interest
Example: "Team plan"
referrerstringHow they heard about it
Example: "newsletter"
referral_codestringReferral code from a prior signup; bumps that signup’s position when honoured
Example: "k3x9q2"
metadataobjectValues for the waitlist's custom fields (`custom_fields[].key` to value), and anything else you want stored on the entry.
Example: {"company":"Acme"}
recaptcha_tokenstringreCAPTCHA v3 token, created with the action `waitlist_signup`. Required when the waitlist has a reCAPTCHA site key; verified server-side with the secret key saved on the waitlist.
Example: "03AFcWeA6…"
variant_idstring · uuidVariant id this submission was attributed to. Customer frontends fetch the active variant from `GET /v1/waitlists/:workspaceSlug/:waitlistSlug` and round-trip it here on POST so per-variant conversion can be computed without a separate impressions table.
Example: "5e1f3a2b-8c4d-4e6f-9a0b-1c2d3e4f5a6b"
Response · 201 Entry created. Persist `referral_code` client-side to build the referral URL; `status` is `approved` when the waitlist auto-approves. A sign-up from an Amazon SES mailbox-simulator address (`…@simulator.amazonses.com`) is stored as a test entry (`is_test: true`, negative `position`), so test runs never land on the real list.
id*string · uuidEntry id.
email*stringNormalised (lower-cased) email.
name*stringName given at sign-up (empty string when none).
position*numberImmutable signup position (1-based order of signup). Negative for a test sign-up (`is_test: true`), which takes no place in line.
is_test*boolean`true` when the email is an Amazon SES mailbox-simulator address (`…@simulator.amazonses.com`). Such a sign-up is stored as a test entry: it is left out of counts, analytics, exports and webhooks, and only the welcome email (to the simulator) goes out.
status*object`approved` when the waitlist auto-approves; `pending` when admin approval is required.
referral_code*stringReferral code for this signup. Build your referral URL from it and pass it as `referral_code` on subsequent signups.
created_at*string · date-timeWhen the entry was created.
effective_position*numberVisible position after applying the referral boost — "you would be #N if approved now". Equals `position` at signup time (no referrals yet), and always for a test sign-up.
Example
Request
POST https://api.waitlist.productcraft.co/v1/waitlists/{workspace_slug}/{waitlist_slug}/entries
Content-Type: application/json
{
"email": "ada@example.com",
"name": "Ada Lovelace",
"interest": "Team plan",
"referrer": "newsletter",
"referral_code": "k3x9q2",
"metadata": {
"company": "Acme"
},
"recaptcha_token": "03AFcWeA6…",
"variant_id": "5e1f3a2b-8c4d-4e6f-9a0b-1c2d3e4f5a6b"
}Response
{
"id": "00000000-0000-0000-0000-000000000000",
"email": "string",
"name": "string",
"position": 0,
"is_test": false,
"status": {},
"referral_code": "string",
"created_at": "2026-01-01T00:00:00.000Z",
"effective_position": 0
}