Advanced

API Reference

Waitlister provides a REST API that lets you programmatically add subscribers and track views. This guide explains how to integrate your applications with our API.

Authentication

All API requests require authentication using an API key. Include your key in the X-Api-Key header with each request.

Getting Your API Key

1. Go to "Overview" page
2. Click the highlighted value under "API key"
3. On the opened modal, click "Generate API key"

Important: Keep your API key secure and never expose it in client-side code. You can regenerate your key at any time, which will invalidate the previous one.

Endpoints

Add Subscriber

POST https://waitlister.me/api/v1/waitlist/{waitlist-key}/sign-up

Adds a new subscriber to your waitlist.

Request Headers

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

Request Body

{
  "email": "user@example.com",    // Required
  "name": "John Doe",            // Optional
  "metadata": {                  // Optional
    "referred_by": "happy-star-4f3d",  // Optional: referral code of the referrer
    "referring_domain": "google.com", // Optional: override HTTP referrer
    "custom_field": "value"      // Any additional custom fields
  }
}

Response

{
  "success": true,
  "is_new_sign_up": true,        // false if email already registered
  "message": "Successfully signed up",
  "position": 42,                // position in waitlist
  "referral_code": "happy-star-4f3d",  // subscriber's referral code
  "redirect_url": "https://waitlister.me/thank-you/waitlist-key/token"  // pre-built thank you page
}

You can either:

• Redirect the subscriber to the redirect_url to use Waitlister's thank you page
• Display a custom message with their position and referral code

Log View

POST https://waitlister.me/api/v1/waitlist/{waitlist-key}/log-view

Records a view of your waitlist.

Request Headers

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

Request Body

{
  "visitor_id": "unique-visitor-id",  // Optional: prevent duplicate views
  "metadata": {                       // Optional
    "referring_domain": "google.com", // Optional: override HTTP referrer
    "custom_field": "value"           // Any additional custom fields
  }
}

Response

{
  "success": true,
  "message": "Successfully logged view"
}

Or if the view was already logged for this visitor:

{
  "success": false,
  "message": "View already logged for this visitor"
}

Rate Limits

• Sign-up endpoint: 60 requests per minute
• Log view endpoint: 200 requests per minute

When you exceed the rate limit, the API will respond with a 429 status code. We recommend implementing exponential backoff in your applications.

Response Codes

The API uses conventional HTTP response codes.

• 200 — Success
• 400 — Bad request (invalid parameters)
• 401 — Invalid API key
• 429 — Rate limit exceeded
• 500 — Server error

Example Implementation

async function addSubscriber(email, name, referredBy) {
  try {
    const response = await fetch('https://waitlister.me/api/v1/waitlist/your-waitlist-key/sign-up', {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
        'X-Api-Key': 'your-api-key'
      },
      body: JSON.stringify({
        email,
        name,
        metadata: {
          referred_by: referredBy
        }
      })
    });

    const data = await response.json();
    
    if (!response.ok) {
      throw new Error(data.error.message);
    }

    if (data.success) {
      // Either redirect to Waitlister's thank you page
      window.location.href = data.redirect_url;
      
      // Or show your own thank you message
      showCustomThankYou({
        position: data.position,
        referralCode: data.referral_code
      });
    }

    return data;
  } catch (error) {
    console.error('Error:', error);
    throw error;
  }
}

Help

Need help? You can contact us via the public contact form or the "Help" page in your account dashboard.