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 three 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 tiny script (~3KB) 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

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 must be alphanumeric, underscore, or hyphen (max 50 characters)
• • Field values max 5,000 characters each
• • Total payload limit: 50KB
• • HTML tags are automatically stripped from submitted values
• • All fields appear as columns in your dashboard and CSV exports

Redirects & Success Messages

Control what happens after someone submits your form.

Custom redirect (Form Action URL method)

Add a hidden field named _next with your thank-you page URL:

<form action="https://api.waitloop.io/f/YOUR_KEY" method="POST">
  <input type="hidden" name="_next" value="https://yoursite.com/thanks" />
  <input name="email" type="email" required />
  <button type="submit">Join</button>
</form>

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.

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

Override widget defaults with data attributes or dashboard settings.

<!-- Override button color and text via attributes -->
<div data-waitloop="YOUR_KEY"
     data-button-text="Get Early Access"
     data-button-color="#10b981"></div>
<script src="https://forms.waitloop.io/w.js"></script>

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 page URL or referrer query strings. No configuration required.

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)

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

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.

Available on Business plans and above.

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.