Creating Waitlists

Create, configure, and manage your waitlists.

Create a Waitlist

From the Dashboard, click Create Waitlist and enter a name. The waitlist is immediately live and ready to accept signups.

Each waitlist gets:

• A unique UUID (e.g., a1b2c3d4-e5f6-7890-abcd-ef1234567890)
• A hosted signup page at /waitlist.html?id=YOUR_ID
• An embeddable widget code
• A shareable link you can copy from the dashboard

Waitlist Settings

Click Edit on any waitlist card to configure it. All settings are optional — the defaults work out of the box.

Display Settings

Field Visibility

Control which fields appear on the signup form:

When set to required, signups must fill in the field to submit. When optional, the field appears but can be left blank. When hidden, the field is not shown.

Custom Questions

Add up to 10 custom questions to your signup form. Each question has:

Custom question answers are included in CSV exports and API responses. See the Custom Questions Format section below for the full JSON structure.

Waitlist Status

Control whether your waitlist is accepting signups:

Close your waitlist when you’re ready to launch or have enough signups. You can reopen it at any time.

Social Proof

The message adapts to the number of signups:

• 1–50: “Others are already signing up”
• 51–100: “Dozens have already joined”
• 101–500: “Hundreds are already in line”
• 501–1,000: “{count} people on the waitlist”
• 1,000+: “{count} people on the waitlist”

Social proof is shown on both the hosted signup page and the embed widget.

Consent Checkbox

Collect explicit consent from signups before they join your waitlist:

When enabled:

• The checkbox is unchecked by default
• The submit button is disabled until the checkbox is checked
• The server rejects signups without consent (400 Bad Request)
• A full consent record is stored with each signup: consent_given_at (ISO timestamp), consent_text_version, and privacy_policy_version
• Consent fields are included in CSV exports

Custom Share Message

Set a custom share message that appears when users click the sharing buttons on the success page:

PATCH /waitlists/{waitlist_id}
{
  "settings": {
    "share_message": "I just signed up for early access — join me!"
  }
}

The share message is used as the pre-filled text for X/Twitter, LinkedIn, Facebook, and WhatsApp sharing buttons on the success page and in the embed widget. If not set, a default message is used (e.g., “I just joined the {waitlist name} waitlist! Join too:”).

Referral Boost

By default, each referral moves the referrer up by 1 position. Increase this to reward sharing more aggressively. For example, setting it to 5 means each referral jumps the referrer up 5 positions.

Position Offset (Advanced+)

When set, all position numbers shown to signups are inflated by this amount. For example, with an offset of 500, the first signup sees “You’re #501 in line” instead of “#1”. Internal positions (used for referral ranking) are not affected.

Referral Notifications (Pro)

When enabled, referrers receive an email like: “Someone just joined using your referral link. You’ve moved up to position X. Keep sharing!” Notifications are rate-limited to one per referrer per hour.

Notifications (Pro)

Set up real-time notifications when someone joins your waitlist:

See Webhooks & Integrations for payload formats and setup guides.

Access Control (Advanced+)

These settings require an Advanced plan or higher:

Email Templates (Pro)

Assign email templates to each waitlist so different waitlists send different emails. Each waitlist can have its own template for:

Set these from the dashboard under Edit > Email Templates, or via the API using the email_templates setting. See Per-Waitlist Template Assignment for details.

Referral Milestones (Pro)

When a referrer’s count reaches one of your thresholds, they automatically receive the referral milestone email template assigned to the waitlist. See Referral Milestones for setup details.

Email Verification (Pro)

When enabled, signups receive a verification email with a link they click to confirm their address.

Update a Waitlist

Settings are merged when you update — only the fields you change are modified. Omitted fields keep their current values.

API: PATCH /waitlists/{waitlist_id}

{
  "name": "Updated Name",
  "settings": {
    "headline": "Join the Beta",
    "phone_field": "required"
  }
}

The request body accepts two top-level fields:

Complete Settings Reference

Every field below is optional. Pass only the fields you want to change inside the settings object. All other fields retain their current values.

Display

Form Fields

Behavior

Access Control (Advanced+)

These settings require an Advanced plan or higher. Attempting to set them on a lower plan returns 403 TIER_REQUIRED.

Notifications (Pro)

These settings require a Pro plan. Attempting to set them on a lower plan returns 403 TIER_REQUIRED.

Email & Verification (Pro)

These settings require a Pro plan.

Custom Questions Format

The custom_questions setting accepts an array of question objects. Each object has:

Example:

{
  "settings": {
    "custom_questions": [
      {
        "id": "company_size",
        "label": "How big is your company?",
        "type": "dropdown",
        "required": true,
        "options": ["1-10", "11-50", "51-200", "200+"]
      },
      {
        "id": "use_case",
        "label": "What will you use this for?",
        "type": "text",
        "required": false
      },
      {
        "id": "newsletter",
        "label": "Subscribe to our newsletter",
        "type": "checkbox"
      }
    ]
  }
}

Custom question answers are included in CSV exports and API responses.

Status Transitions

When you set status to "closed":

• The hosted signup page shows a “Waitlist Closed” message instead of the form
• The embed widget displays a closed state
• Any attempt to sign up via the API returns a 403 error with code WAITLIST_CLOSED
• Existing signups, positions, and referral links are preserved — nothing is deleted

When you set status back to "open":

• The signup form is immediately available again
• All existing signups retain their positions
• Referral links start working again

You can toggle between "open" and "closed" as many times as you want. This is useful for pausing signups temporarily (e.g., during maintenance) or permanently closing the waitlist when you launch.

Delete a Waitlist

Click Delete on a waitlist card and confirm. All data is permanently deleted, including signup records, analytics, and blasts.

Related

• Signup Form — how the public signup form works and what happens when someone joins
• Embed Widget — add a signup form to any website with one line of code
• Managing Signups — list, export, delete, and import signups on your waitlists