Waitlist docs
Getting started

Launch a waitlist.

Render the signup form on your own frontend; the API surface to submit an entry is one POST.

1

Enable Waitlist on your workspace

Open the Waitlist area in the console. If your workspace doesn't have Waitlist enabled yet, a workspace owner needs to turn it on under Workspace → Services in the sidebar — find the Waitlist row and hit Enable.

2

Create it, then activate it

From the Waitlist area, click New waitlist and give it a slug plus a display name. A new waitlist starts in draft: the public endpoints below return 404 / 422 until you open the waitlist and hit Activate.

Capacity, manual-approval mode, referral boost, the confirmation message and reCAPTCHA all live on the waitlist's Settings tab — none of them are required to take your first signup.

3

Post entries from your own frontend

Render the signup form on your own site and POST entries straight to the public entries endpoint. No auth header needed — the URL itself is the credential:

bash
curl -X POST -H "content-type: application/json" \
  -d '{
    "email": "ada@example.com",
    "name": "Ada Lovelace",
    "metadata": { "company": "Analytical Engines Inc." }
  }' \
  https://api.waitlist.productcraft.co/v1/waitlists/<workspace-slug>/<waitlist-slug>/entries

email and name are the only required fields; anything else you collect goes in metadata. The response gives you the position and referral code to render:

201 Created
{
  "id": "627bc8ef-ce0f-47f5-afd4-8636961b1c82",
  "email": "ada@example.com",
  "name": "Ada Lovelace",
  "position": 1,
  "effective_position": 1,
  "status": "approved",
  "referral_code": "897TKH3C",
  "created_at": "2026-07-28T20:08:38.910Z"
}

A duplicate email on the same waitlist returns 409, a disposable-email domain returns 400, and the endpoint is rate-limited per IP (429). See the API reference for the full request and response shapes.

4

Webhooks for entry events

Webhooks are configured per workspace (console → Webhooks), not per waitlist, and every payload carries a waitlist_id so you can route server-side. You subscribe to any of three events: entry.created, entry.approved, entry.rejected.

Each delivery is signed with HMAC-SHA256 in the X-Waitlist-Signature header (t=<unix_ts>,v1=<hex>) alongside X-Waitlist-Event and X-Waitlist-Event-Id. The signing secret is revealed exactly once, when the webhook is created — store it then. Every attempt is recorded on the webhook's deliveries log, and 20 consecutive failures (or 24h of continuous failure) auto-disables the webhook.

Next

Where to go from here

  • API reference — every endpoint with request and response schemas.
  • Manage entries — bulk approve / reject from the console, or via PATCH /v1/workspaces/:workspaceId/waitlists/:waitlistId/entries/:entryId with { "status": "approved" | "rejected" }. The admin lane takes a session cookie or a Bearer personal access key, and :workspaceId is the workspace UUID.
  • Analytics — GET /v1/workspaces/:workspaceId/waitlists/:waitlistId/analytics returns totals, a by_status breakdown, signups today / this week / this month, and top referrers.
Open the API referenceBack to the console