Waitlist API reference

Waitlist API · Public-Waitlist

post/v1/waitlists/{workspace_slug}/{waitlist_slug}/entries

Submit 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*string

Slug of the workspace that owns the waitlist (a renamed workspace's old slug still resolves).

waitlist_slug*string

Slug of the waitlist within its workspace.

Headers

Idempotency-Keystring

Idempotency 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*string

Email address

Example: "ada@example.com"

name*string

Full name

Example: "Ada Lovelace"

intereststring

Free-text product interest

Example: "Team plan"

referrerstring

How they heard about it

Example: "newsletter"

referral_codestring

Referral code from a prior signup; bumps that signup’s position when honoured

Example: "k3x9q2"

metadataobject

Values for the waitlist's custom fields (`custom_fields[].key` to value), and anything else you want stored on the entry.

Example: {"company":"Acme"}

recaptcha_tokenstring

reCAPTCHA 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 · uuid

Variant 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 · uuid

Entry id.

email*string

Normalised (lower-cased) email.

name*string

Name given at sign-up (empty string when none).

position*number

Immutable 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*string

Referral code for this signup. Build your referral URL from it and pass it as `referral_code` on subsequent signups.

created_at*string · date-time

When the entry was created.

effective_position*number

Visible 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
}