Waitlist API reference

Waitlist API · Waitlists

post/v1/workspaces/{workspace_id}/waitlistsAuth

Create a waitlist (workspace-scoped)

Pass `status: "active"` to accept public sign-ups straight away. Without it the waitlist starts as a draft, and the response says so in `accepting_signups: false` and `signups_note`.

Path parameters

workspace_id*string · uuid

Id of the workspace.

Headers

Idempotency-Keystring

Stripe-style idempotency key. Waitlist creation provisions a non-trivial sub-tree (variant, default referral settings, etc.); a retry without this header creates a second waitlist sharing the same name slug. 24h TTL.

Request body

slug*string

URL-safe slug

Example: "early-access"

display_name*string

Display name

Example: "Early Access Program"

descriptionstring

Description returned in the public waitlist payload — customer frontends typically render it under the display name on their signup form.

Example: "Be first to try the new editor."

settingsobject

Waitlist settings (max_entries, approval_required, custom_fields, confirmation_message, referral_boost, referral_rewards, recaptcha_site_key). To turn on reCAPTCHA v3, send recaptcha_site_key together with recaptcha_secret_key (both from your reCAPTCHA admin console); the secret is stored encrypted and is never returned. Send recaptcha_site_key: null to turn it off.

Example: {"approval_required":false,"max_entries":1000}

statusenum (2)

Start state. `active` accepts public sign-ups straight away; `draft` (the default) refuses them with 422 until the status is changed to `active`.

Example: "active"

allowed_originsarray

Web origins (scheme and host, for example `https://acme.com` or `http://localhost:3000`) that browsers may submit public sign-ups from. `https://*.acme.com` matches any subdomain. An empty list means any origin. A browser request from another origin gets 403 `ORIGIN_NOT_ALLOWED`; server-side calls without an `Origin` header are not checked. Entries are normalised (lower case, no trailing slash, default port dropped).

Example: ["https://acme.com","https://*.acme.com"]

Response · 201 Waitlist created.

id*string · uuid

Waitlist id.

Example: "33a8b309-8753-4f08-90d7-9dc484eff392"

workspace_id*string · uuid

The workspace that owns the waitlist.

Example: "9b2f6c1e-0d6a-4a63-9a43-2f1c3e4d5a6b"

workspace_slug*string

Slug of the workspace, used in the public routes.

Example: "acme"

slug*string

Waitlist slug, unique in the workspace; used in the public routes.

Example: "early-access"

display_name*string

Display name.

Example: "Early Access Program"

description*string

Description shown on the public info; null when unset.

status*object

`active` accepts public sign-ups; `draft` and `paused` refuse them; `closed` ends the waitlist.

accepting_signups*boolean

Whether the public sign-up endpoint accepts entries right now (only an `active` waitlist does).

Example: false

signups_note*string

Plain explanation when public sign-ups are refused, and how to open them; null when the waitlist is active.

Example: "This waitlist is a draft, so public sign-ups are refused (422) until you change its status to active."

allowed_origins*array

Web origins (scheme and host, for example `https://acme.com` or `http://localhost:3000`) that browsers may submit public sign-ups from. `https://*.acme.com` matches any subdomain. An empty list means any origin. A browser request from another origin gets 403 `ORIGIN_NOT_ALLOWED`; server-side calls without an `Origin` header are not checked. Entries are normalised (lower case, no trailing slash, default port dropped).

Example: []

settings*object

Waitlist settings (max_entries, approval_required, custom_fields, confirmation_message, referral_boost, referral_rewards, recaptcha_site_key). The reCAPTCHA secret key is never returned; recaptcha_secret_configured says whether one is saved.

created_by*string

Id of the user or API key that created the waitlist.

previous_workspace_slug*string

The workspace's slug before its last rename; the public routes still answer under it. Null when never renamed.

created_at*string · date-time

When the waitlist was created.

updated_at*string · date-time

When the waitlist was last changed.

Example

Request

POST https://api.waitlist.productcraft.co/v1/workspaces/{workspace_id}/waitlists
Authorization: Bearer YOUR_TOKEN
Content-Type: application/json

{
  "slug": "early-access",
  "display_name": "Early Access Program",
  "description": "Be first to try the new editor.",
  "settings": {
    "approval_required": false,
    "max_entries": 1000
  },
  "status": "active",
  "allowed_origins": [
    "https://acme.com",
    "https://*.acme.com"
  ]
}

Response

{
  "id": "33a8b309-8753-4f08-90d7-9dc484eff392",
  "workspace_id": "9b2f6c1e-0d6a-4a63-9a43-2f1c3e4d5a6b",
  "workspace_slug": "acme",
  "slug": "early-access",
  "display_name": "Early Access Program",
  "description": "string",
  "status": {},
  "accepting_signups": false,
  "signups_note": "This waitlist is a draft, so public sign-ups are refused (422) until you change its status to active.",
  "allowed_origins": [],
  "settings": {},
  "created_by": "string",
  "previous_workspace_slug": "string",
  "created_at": "2026-01-01T00:00:00.000Z",
  "updated_at": "2026-01-01T00:00:00.000Z"
}