Waitloop Documentation

Everything you need to start collecting waitlist signups. Point your form, get a dashboard, grow your audience.

Quickstart

Get your first waitlist collecting signups in four steps.

<form action="https://api.waitloop.io/f/YOUR_KEY" method="POST">
  <input name="email" type="email" required />
  <button type="submit">Join Waitlist</button>
</form>

Your Form Key

Every waitlist you create gets a unique form key. This key identifies your list and routes submissions to the right place.

• • Format: wz_ followed by 24 characters
• • Found in your dashboard under each list's detail page
• • Copy-to-clipboard buttons are available for all embed code snippets
• • You can regenerate a key at any time (old key stops working immediately)

Method 1: Form Action URL

The simplest integration. No JavaScript required. Just change your form's action attribute.

<!-- Just change the action URL. That's it. -->
<form action="https://api.waitloop.io/f/YOUR_KEY"
      method="POST">
  <input name="email" type="email" required />
  <input name="name" type="text" />
  <button type="submit">Join</button>
</form>

How it works

• • The endpoint accepts both application/x-www-form-urlencoded and application/json
• • All named fields are auto-detected and stored
• • Browser form submissions get a 302 redirect (to your thank-you page or Waitloop's default)
• • JSON submissions get a JSON response back

Auto-captured metadata

Every submission automatically captures this data with no extra code:

Method 2: Script Tag (AJAX)

Add our script (~14KB gzipped, no dependencies) to get AJAX form submission with no page reload. Inline success and error messages appear right in the form.

<!-- Your existing form -->
<form data-waitloop="YOUR_KEY">
  <input name="email" type="email" required />
  <button type="submit">Join Waitlist</button>
</form>

<!-- Add right before </body> -->
<script src="https://forms.waitloop.io/w.js"></script>

What the script does

• • Finds all forms with the data-waitloop attribute
• • Intercepts form submissions and sends them via fetch()
• • Shows inline success or error messages (no page redirect)
• • Sends the current page URL as context automatically
• • Detects referral codes from ?ref= query parameters
• • Includes a hidden honeypot field for spam protection

Method 3: Auto-Generate Form

Drop an empty div and Waitloop renders a complete form for you. Configure the fields, colors, and text from your dashboard.

<!-- Just drop this where you want the form -->
<div data-waitloop="YOUR_KEY"></div>
<script src="https://forms.waitloop.io/w.js"></script>

How it works

• • When the div has no form inside it, the widget auto-generates one
• • Form fields are configured per-list from your dashboard's Widget Builder
• • Uses Shadow DOM encapsulation so it never conflicts with your site's CSS
• • "Powered by Waitloop" branding is removable on Pro plans and above

Data attributes

Colors, fonts, and field layout are set in the dashboard's Widget Builder rather than by attribute — see Styling Options. Text strings can also be overridden per form; see Per-Form Text Overrides.

Custom Fields

Waitloop captures any named field in your form. Email, name, company, phone, role - whatever your form has, we store it.

<form action="https://api.waitloop.io/f/YOUR_KEY" method="POST">
  <input name="email" type="email" required />
  <input name="name" type="text" />
  <input name="company" type="text" />
  <select name="role">
    <option value="developer">Developer</option>
    <option value="designer">Designer</option>
    <option value="founder">Founder</option>
  </select>
  <button type="submit">Join</button>
</form>

Field rules

• • Field names may contain letters, digits, underscores, and hyphens, and must start with a letter or underscore. Max 50 characters.
• • Up to 20 fields per submission
• • Field values max 1,000 characters each; email addresses max 254
• • Total payload limit: 50KB for text-only submissions (forms that send files are covered in File Uploads)
• • Names beginning with an underscore are reserved for Waitloop's own use — avoid them for your own fields
• • All fields appear as columns in your dashboard and CSV exports

File Uploads

Your form can collect images alongside the usual text fields — product photos, headshots, screenshots, portfolio pieces, contest entries. Files arrive attached to the signup and are viewable and downloadable from your dashboard.

File uploads are off by default on every list. Switching them on takes three steps.

Using the widget (Script Tag or Auto-Generate)

Nothing to do. Once the field is saved, the widget renders the file picker for you, uploads each file as the visitor chooses it, shows the selected filenames, and blocks submission until the uploads finish. Your existing embed snippet doesn't change.

Using your own HTML form

Add enctype="multipart/form-data" to your <form> tag — without it the browser sends only the filename, not the file — then add a file input whose name matches your field name from step 2.

<form action="https://api.waitloop.io/f/YOUR_KEY" method="POST"
      enctype="multipart/form-data">
  <input name="email" type="email" required />
  <input name="photo" type="file" accept="image/*" />
  <button type="submit">Join Waitlist</button>
</form>

To let someone attach several files to one field, add the multiple attribute and raise Max files on the field to match.

Using your own JavaScript

Post a FormData object. Let the browser set the request headers — if you set Content-Type yourself the upload boundary is lost and the request fails.

const data = new FormData();
data.append('email', 'ada@example.com');
data.append('photo', fileInput.files[0]);

const res = await fetch('https://api.waitloop.io/f/YOUR_KEY', {
  method: 'POST',
  body: data
});

Supported file types

Waitloop accepts images only. Every upload is checked to confirm its actual content matches its extension, so a document renamed to .png is rejected.

PDFs, documents, archives, and video aren't accepted. SVG is excluded too, because SVG files can carry executable script. If you need a document from a signup, collect a link to it in a URL field instead.

Limits by plan

Your plan sets the ceiling. List and field settings can go lower, never higher.

Finding your files

• • Open any signup from the Submissions tab. An Attachments panel lists every file with its size, plus a thumbnail gallery you can click through.
• • Download next to any file saves the original. Download links are short-lived and generated on demand, so files are never publicly browsable.
• • In CSV exports and webhook payloads, the file field's value is the filename (or a comma-separated list). Download the files themselves from the dashboard.
• • Uploads count toward your plan's storage. Deleting a submission — individually, in bulk, or through a GDPR erasure request — deletes its files too and frees the space. Your list's data-retention setting removes them on schedule.

If an upload is rejected

Visitors see the reason inline. Here's what each message points to:

Redirects & Success Messages

Control what happens after someone submits your form.

Custom redirect (Form Action URL method)

Redirects are set in the dashboard, not in your HTML. After a plain form post, Waitloop sends the browser to the first of these that's set:

1. The Thank-You URL on the list — list Settings tab. Use this when one list needs its own destination.
2. The Default Thank-You URL on your account — Settings page. Applies to every list that doesn't set its own.
3. If neither is set, the visitor returns to the page they submitted from with ?waitloop=success appended, so you can show your own confirmation.

https://yoursite.com/landing?waitloop=success

Custom success message (Script Tag / Auto-Generate methods)

When using the widget script, the success message is configured from your dashboard settings. The message appears inline within the form area after a successful submission.

Responses & Errors

Only needed if you're posting to Waitloop from your own code. The widget handles all of this for you.

Which response you get

• • Post application/json and you always get JSON back.
• • Post a plain HTML form and you get a 302 redirect, as described in Redirects.
• • Posting files is ambiguous — a script wants JSON, a real form wants a redirect. Send Accept: application/json to get JSON; otherwise you get the redirect.

Successful signup

{
  "success": true,
  "message": "You're on the list!",
  "position": 42,
  "referralCode": "wz_8kT4mNpQ2xY7"
}

Errors

Every failure uses the same envelope. Show error.message to your visitor — it's already written for them.

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid email address."
  }
}

Managing Lists

Each waitlist is a separate list with its own form key, submission data, and settings. One account can have multiple lists.

Actions

• • Create - Click "Create List" from the dashboard. A form key is generated automatically.
• • Rename - Edit the list name any time from the list detail page.
• • Pause - Temporarily stop accepting new submissions. Existing data is preserved.
• • Archive - Move the list to archived state. Submissions are rejected.
• • Delete - Permanently remove the list and all its data (requires confirmation).
• • Regenerate Key - Get a new form key. The old key stops working immediately.

List statuses

Viewing Submissions

All captured form data is available in a sortable, searchable table.

• • Dynamic columns - Columns auto-populate based on the fields your form submits
• • Sort - Click any column header. Newest first by default.
• • Search & filter - Search by any field value. Filter by spam status (all / clean / suspicious / spam).
• • Pagination - Choose 25, 50, or 100 per page.
• • Delete - Remove individual submissions or use bulk selection to delete multiple at once.
• • Mark spam - Flag or unflag submissions as spam individually or in bulk.

CSV Export

Download your entire waitlist data as a CSV file, ready for any spreadsheet or CRM tool.

• • One-click export from any list's detail page
• • Includes all dynamic form fields as columns
• • Metadata columns: referrer, page URL, UTMs, timestamp
• • Optional PII masking toggle to anonymize personal data before download
• • Every export is logged in the audit trail (who, when, which list, row count)
• • Rate limited to 5 exports per minute to prevent abuse

Settings

Configure your account from the Settings page in the dashboard.

Widget Builder

A visual tool in your dashboard to customize the look and feel of the embeddable widget. No code needed.

Customization options

• • Button text - Change the submit button label
• • Button color - Pick any color with the color picker
• • Form fields - Add, remove, and reorder fields
• • Labels & placeholders - Customize field labels and placeholder text
• • Success message - Set the message shown after a successful signup

Styling Options

Appearance is set once in the dashboard and applies everywhere you've embedded that form — no CSS to write and no styles to keep in sync across pages. Open your list, go to the Form Creator, and use the Theme panel:

• • Colors — button and button text, form background and text, labels, and input background, border, and text
• • Shape & type — corner radius, font family, and the width at which the form switches to its narrow layout
• • Layout — stacked, inline, or two-column, with field labels shown or hidden
• • Content — form title, description, button text, success message, and the "Powered by Waitloop" credit

Only text strings can be overridden per embed, using data-* attributes — useful when the same form appears on several pages with different wording. See Per-Form Text Overrides.

Live Preview

See changes in real-time as you adjust settings in the Widget Builder.

• • Toggle between desktop and mobile preview modes (320px mobile width)
• • Updates instantly as you change button text, colors, or fields
• • Shows exactly what your users will see on their website

Analytics Overview

Built-in analytics give you insights into your signups without any external tracking tools.

Signups over time

• • Bar chart showing daily signups for single list or all lists
• • Date range picker: 7 days, 30 days, 90 days, or custom range
• • Period-over-period comparison (compare current range to previous)

Top pages

See which pages on your site drive the most signups, based on the pageUrl metadata.

Usage stats

• • See submissions this month vs your plan limit
• • Visual progress bar with percentage
• • Upgrade prompt at 80% usage

Traffic Sources

Understand where your signups come from.

• • Referral sources bar chart - Top referring domains ranked by signup count
• • Full referrer table - Complete referrer URLs with individual counts
• • All data captured automatically from HTTP headers - no tracking code needed

UTM Tracking

Waitloop automatically captures UTM parameters from the address of the page the form was submitted from. No configuration required — but it does require the widget script, since a plain form post doesn't send the page address. Use Method 2 or Method 3 for campaign tracking.

Supported parameters

• • utm_source - Where the traffic came from (e.g. twitter, newsletter)
• • utm_medium - Marketing medium (e.g. social, email, cpc)
• • utm_campaign - Campaign name (e.g. launch-2026, black-friday)
• • utm_term and utm_content - Captured and stored with each submission

Campaign breakdown

View a table of all campaigns with source, medium, and signup counts. Filter by date range to compare campaign performance.

Referral & Viral Loop

Turn signups into growth with built-in viral referral tracking.

Available on Pro plans and above.

How it works

1. Someone signs up for your waitlist
2. They receive a unique referral code and shareable link
3. When their friends sign up using that link, the referrer gets credit
4. Successful referrals boost the referrer's position in the queue

Referral link format

https://yoursite.com?ref=REFERRAL_CODE

Position tracking

• • Each signup gets a position number in the list
• • The widget can display position after signup
• • Referrals move the referrer up in the queue

Leaderboard

View a referral leaderboard in your analytics dashboard showing top referrers and their referral counts.

Webhooks

Get notified instantly when someone signs up. Send data to Zapier, Make, Slack, or your own server.

Available on Pro plans and above.

Setup

1. Go to your list's detail page in the dashboard
2. Enter your webhook URL
3. Enable the webhook toggle
4. Click "Test" to send a sample payload

Payload

Each new submission triggers a POST request to your URL with a JSON payload containing all form fields and metadata.

Security

• • Every webhook is signed with X-Waitloop-Signature header (HMAC-SHA256)
• • A unique webhook secret is auto-generated per list
• • Verify the signature on your server to ensure authenticity

Retry behavior

Failed deliveries are retried 3 times with exponential backoff (2s, 8s, 32s). View delivery logs in your dashboard.

Email Notifications

Stay informed about your waitlist activity without checking the dashboard.

Signup notifications

• • Off - No email notifications
• • Instant - Get notified for each new signup (grouped hourly)
• • Daily digest - One summary email at 8AM UTC

What's in an instant notification

The instant email carries the whole submission, so you can act on it without opening the dashboard:

• • A summary line — list, project, submitter email, queue position, time, and form key
• • Every field the visitor filled in, labelled the way your form labels it and in the same order
• • A thumbnail of each uploaded image, with a link to download the original at full size

Image links in email are valid for 7 days and work without signing in, so treat the email as you would the files themselves — forwarding it shares the images. The copies in your dashboard never expire. Very long answers are trimmed in the email; the full value is always in the dashboard and CSV export.

Milestone alerts

Automatic email when your list hits: 100, 500, 1K, 5K, 10K, 50K, or 100K signups. Each milestone only triggers once.

Security alerts

• • Password changes
• • Login from a new device or IP address
• • Account lockout events
• • Plan usage at 80% and 100% of limit

Custom Email Templates

Customize the emails Waitloop sends on your behalf.

Template types

Editor features

• • Variable interpolation (name, email, position, referral count, etc.)
• • Live preview with sample data
• • Reset to default template at any time

A/B Testing

Test different form variants to optimize conversion rates.

Available on Business plans and above.

How it works

• • Create multiple form variants per list from the list detail page
• • Set traffic weight for each variant (e.g. 50/50, 70/30)
• • Visitors are randomly assigned to a variant
• • Variant assignment is tracked in submission metadata
• • Compare conversion rates across variants in the dashboard

Team Members

Invite your team to collaborate on your waitlists.

Seats included: Sandbox and Starter 1, Pro 3, Business 10, Enterprise unlimited.

Roles

Inviting members

1. Go to the Team page in your dashboard
2. Enter the team member's email address
3. Select their role (Viewer, Editor, or Admin)
4. They'll receive an email invitation to set up their password and join

Internationalization (i18n)

The widget supports 10 built-in languages with RTL support.

Supported languages

Usage

<!-- Set widget language with data-locale -->
<div data-waitloop="YOUR_KEY"
     data-locale="es"></div>
<script src="https://forms.waitloop.io/w.js"></script>

Per-Form Text Overrides

Override any default text string on a per-form basis using data-* attributes. This is useful when you're using the widget for contact forms, demo requests, or anything that isn't a traditional waitlist.

Available attributes

Contact form example

Use text overrides to remove all waitlist language and turn the widget into a generic contact form:

<div data-waitloop="YOUR_KEY"
     data-title="Contact Us"
     data-description="Send us a message and we'll get back to you."
     data-button-text="Send Message"
     data-email-placeholder="Your email address"
     data-success-message="Thanks! We'll be in touch shortly."
     data-show-position="false"
     data-show-referral="false"
     data-invalid-email="Please provide a valid email."
     data-error-message="Could not send. Please try again."></div>
<script src="https://forms.waitloop.io/w.js"></script>

Custom Success Template

For complete control over what appears after a successful submission, place a <template> element inside the widget container. When present, it replaces the entire default success screen.

Basic usage

<div data-waitloop="YOUR_KEY"
     data-title="Request a Demo"
     data-button-text="Request Demo"
     data-show-position="false"
     data-show-referral="false">
  <template data-waitloop-success>
    <div style="text-align:center;padding:20px 0;">
      <h3 style="color:#f8fafc;">Demo Request Received!</h3>
      <p style="color:#94a3b8;">We'll email you to schedule.</p>
    </div>
  </template>
</div>
<script src="https://forms.waitloop.io/w.js"></script>

Available placeholders

Use these placeholders inside your template HTML. They are replaced with real values after submission:

Spam Protection

Multiple layers of protection keep your waitlist clean.

Domain Verification

Verify ownership of your domains with a DNS TXT record for stronger security.

Steps

1. Go to Settings in your dashboard
2. Add your domain
3. Copy the DNS TXT record value provided
4. Add the TXT record to your domain's DNS settings
5. Click "Verify" - verification status updates to confirmed

Verified domains are automatically added to your allowed origins list.

Data Privacy & GDPR

We take data privacy seriously. Here's how Waitloop helps you stay compliant.

Data retention

Configure auto-delete for submissions older than 30, 60, or 90 days. A background job runs daily to clean up expired data. Set to "never" to keep data indefinitely.

Right to erasure (GDPR)

Use the GDPR erasure endpoint to delete all submissions containing a specific email address across all your lists. Returns the count of deleted records and is logged in the audit trail.

PII masking on export

Toggle PII masking when exporting CSV files to anonymize personal data before downloading.

Privacy-safe IP handling

IP addresses are stored as SHA256 hashes - never in plain text. Used only for rate limiting and duplicate detection.

Widget Integrity (SRI)

Ensure the widget script hasn't been tampered with using Subresource Integrity hashes.

How to use SRI

Your dashboard shows the embed snippet with the SRI hash pre-filled:

<script src="https://forms.waitloop.io/w.js"
        integrity="sha384-..."
        crossorigin="anonymous"></script>

The SRI hash is automatically generated during the widget build process and displayed in your dashboard's embed snippets.