API Reference / Endpoints

Create Waitlist

The Create Waitlist endpoint lets you create a new waitlist programmatically — no dashboard step required. The waitlist is created with the same defaults as one created from the dashboard, and signups work immediately via the form-action endpoint or the Add Subscriber endpoint.

This endpoint requires an account API key (wl_acct_…) and is available on every plan, within your plan's waitlist limit.

Want the full picture in one fetch? The one-page integration guide covers every path with copy-paste code · OpenAPI spec · SDK: npm install waitlister

Endpoint Details

URL: https://waitlister.me/api/v1/waitlists
Method: POST

Request

Headers

code

Content-Type: application/json
X-Api-Key: wl_acct_your-account-api-key

Body Parameters

Parameter	Type	Required	Description
`name`	String	Yes	Product / waitlist name (max 100 characters)
`slug`	String	No	URL slug for hosted pages. Derived from `name` when omitted. Slugs are global across Waitlister — if the derived or provided slug is already taken, the request is rejected with `409` (see below)
`category`	String	No	Product category
`description`	String	No	Internal description — not shown publicly
`referral_rewards`	Object	No	Referral program configuration (see below)
`validate_emails`	Boolean	No	Validate email deliverability at sign-up (default `true`)

`referral_rewards` Object

Field	Type	Description
`enabled`	Boolean	Enable the referral program (default `false`)
`signup_points`	Integer	Points awarded on sign-up (default `50`)
`referral_points`	Integer	Points awarded per referral (default `30`)

Example Request

bash

curl -X POST "https://waitlister.me/api/v1/waitlists" \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: wl_acct_your-account-api-key" \
  -d '{
    "name": "My Product",
    "referral_rewards": { "enabled": true }
  }'

Response

Success Response `201`

json

{
  "success": true,
  "data": {
    "waitlist": {
      "id": "aBcDeFgH123",
      "key": "AbC123xYz456",
      "slug": "my-product",
      "name": "My Product",
      "form_action_url": "https://waitlister.me/s/AbC123xYz456",
      "hosted_page_url": null,
      "created_at": 1751700000000
    },
    "notes": "Signups work immediately via form_action_url (whitelist your domain in settings) or POST /api/v1/waitlist/{key}/sign-up with this same account key. The hosted landing page is published from the dashboard."
  }
}

Waitlist Object Fields

Field	Type	Description
`id`	String	Waitlist document ID
`key`	String	Waitlist key — use it in every per-waitlist API path
`slug`	String	URL slug of the waitlist
`name`	String	Waitlist name
`form_action_url`	String	Point any HTML form at this URL to collect signups (whitelist your domain in the waitlist settings first)
`hosted_page_url`	Null	Always `null` at creation — the hosted landing page is published from the dashboard
`created_at`	Number	Creation timestamp (Unix ms)

Error Responses

Status Code	Description
`400`	Missing or invalid `name`, or invalid optional fields
`401`	Missing, invalid, or revoked account API key
`403`	Your plan's waitlist limit is reached — the message states the limit
`409`	The name or slug is already taken, or the name is reserved (see below)
`429`	Rate limit exceeded (5 requests per minute)

Name and Slug Uniqueness

Waitlist names and slugs are globally unique across Waitlister — the same rule the dashboard enforces. Unlike some APIs, this endpoint does not silently rename a colliding waitlist; it rejects the request with 409 so you stay in control of the name.

Name collision (slug derived from name): A waitlist with this name already exists (slug "my-product" is taken — slugs are global across Waitlister). Pass a different "name", or an explicit unique "slug".
Explicit slug collision (you passed slug): Slug "my-product" is already taken (slugs are global across Waitlister). Pass a different "slug".
Reserved name: a name whose slug would be test-waitlist returns This name is not available. Choose a different "name".

What's Created (and What Isn't)

The waitlist is created with dashboard defaults: referral program (disabled unless requested), thank-you page, email preferences, and analytics counters. Form-action signups, API signups, and thank-you pages work immediately.

The hosted landing page and standalone form are not provisioned — those are designed and published from the dashboard. hosted_page_url is null until then.

Next Steps

Add subscribers with the same account key
Read stats for social-proof widgets
Or collect signups without any key via the form-action endpoint