API Reference / Endpoints

Add Subscriber

The Add Subscriber endpoint allows you to programmatically add new subscribers to your waitlist. This is useful for integrating Waitlister with your existing systems or custom sign-up forms.

Endpoint Details

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

Request

Headers

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

Path Parameters

Parameter	Description
`waitlist-key`	Your unique waitlist key, found in your waitlist settings

Request Body

{
  "email": "[email protected]",
  "name": "John Doe",
  "phone": "+1234567890",
  "metadata": {
    "referred_by": "happy-star-4f3d",
    "referring_domain": "google.com",
    "client_ip": "203.0.113.42",
    "fingerprint": "abc123def456",
    "custom_field_1": "value1",
    "custom_field_2": "value2"
  }
}

Required Fields

Field	Type	Description
`email`	String	The subscriber's email address

Optional Fields

Field	Type	Description
`name`	String	The subscriber's name
`phone`	String	The subscriber's phone number
`metadata`	Object	Additional information about the subscriber
`metadata.referred_by`	String	Referral code of the user who referred this subscriber
`metadata.referring_domain`	String	Domain that referred the subscriber (overrides HTTP referrer)
`metadata.client_ip`	String	The end user's IP address. When provided, enables referral fraud detection for API sign-ups. Must be a valid IPv4 address.
`metadata.fingerprint`	String	A device fingerprint for the end user. When provided alongside `client_ip`, strengthens referral fraud detection.
`metadata.*`	Any	Any additional custom fields you want to store with the subscriber

Response

The response format depends on whether your waitlist has double opt-in enabled.

Standard Response (Double Opt-in Disabled) `200`

{
  "success": true,
  "is_new_sign_up": true,
  "is_pending_confirmation": false,
  "message": "Successfully signed up",
  "position": 42,
  "inflated_position": 42,
  "points": 50,
  "referral_code": "happy-star-4f3d",
  "sign_up_token": "abc123xyz",
  "redirect_url": "https://waitlister.me/thank-you/waitlist-key/abc123xyz"
}

Double Opt-in Response (Double Opt-in Enabled) `200`

When double opt-in is enabled, subscribers must confirm their email before being added to your waitlist.

{
  "success": true,
  "is_new_sign_up": true,
  "is_pending_confirmation": true,
  "message": "Please check your email to confirm your sign-up",
  "redirect_url": "https://waitlister.me/confirm-pending/waitlist-key/confirmation-token"
}

Existing Subscriber Response `200`

If the email is already registered:

{
  "success": true,
  "is_new_sign_up": false,
  "is_pending_confirmation": false,
  "message": "Email already registered",
  "position": 42,
  "inflated_position": 42,
  "referral_code": "happy-star-4f3d",
  "sign_up_token": "abc123xyz",
  "redirect_url": "https://waitlister.me/thank-you/waitlist-key/abc123xyz"
}

Pending Confirmation Response (Double Opt-in) `200`

If the email already has a pending confirmation:

{
  "success": true,
  "is_new_sign_up": false,
  "is_pending_confirmation": true,
  "message": "Confirmation email already sent. Please check your inbox.",
  "redirect_url": "https://waitlister.me/confirm-pending/waitlist-key/confirmation-token"
}

Response Fields

Field	Type	Description
`success`	Boolean	Always `true` for successful responses
`is_new_sign_up`	Boolean	`true` if this is a new subscriber, `false` if the email was already registered or pending
`is_pending_confirmation`	Boolean	`true` if the subscriber needs to confirm their email (double opt-in enabled)
`message`	String	A human-readable message
`position`	Number	The subscriber's real position in your waitlist
`inflated_position`	Number	The public-facing position with any position inflation offset applied
`points`	Number	The subscriber's points (only present when confirmed)
`referral_code`	String	The subscriber's unique referral code (only present when confirmed)
`sign_up_token`	String	A unique token for this subscriber (only present when confirmed)
`redirect_url`	String	URL to redirect the user to. Points to the thank-you page (standard) or confirm-pending page (double opt-in)

Error Responses

Bad Request `400`

{
  "statusCode": 400,
  "message": "Valid email is required"
}

Rate Limited `429`

{
  "statusCode": 429,
  "message": "Too many sign-up attempts. Please try again later.",
  "data": {
    "retry_after": 3600
  }
}

Common Error Codes

Status Code	Description
`400`	Invalid email format or missing required field
`429`	Rate limit exceeded
`500`	Internal server error

Examples

curl -X POST "https://waitlister.me/api/v1/waitlist/your-waitlist-key/sign-up" \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: your-api-key" \
  -d '{
    "email": "[email protected]",
    "name": "John Doe"
  }'

curl -X POST "https://waitlister.me/api/v1/waitlist/your-waitlist-key/sign-up" \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: your-api-key" \
  -d '{
    "email": "[email protected]",
    "name": "Jane Smith",
    "metadata": {
      "referred_by": "happy-star-4f3d"
    }
  }'

curl -X POST "https://waitlister.me/api/v1/waitlist/your-waitlist-key/sign-up" \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: your-api-key" \
  -d '{
    "email": "[email protected]",
    "name": "John Doe",
    "metadata": {
      "company": "Acme Inc",
      "role": "Developer",
      "how_they_heard": "Google Search"
    }
  }'

curl -X POST "https://waitlister.me/api/v1/waitlist/your-waitlist-key/sign-up" \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: your-api-key" \
  -d '{
    "email": "[email protected]",
    "name": "Jane Smith",
    "metadata": {
      "referred_by": "happy-star-4f3d",
      "client_ip": "203.0.113.42",
      "fingerprint": "abc123def456"
    }
  }'

Implementation Notes

Handling the Response

Check the is_pending_confirmation field to determine the appropriate user experience:

const response = await fetch('https://waitlister.me/api/v1/waitlist/your-key/sign-up', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-Api-Key': 'your-api-key'
  },
  body: JSON.stringify({ email: '[email protected]', name: 'John' })
})

const data = await response.json()

if (data.is_pending_confirmation) {
  // Double opt-in: Show "check your email" message
  showMessage('Please check your email to confirm your subscription.')
  // Optionally redirect to the confirm-pending page
  // window.location.href = data.redirect_url
} else {
  // Standard flow: Show success with position
  showMessage(`You're #${data.position} on the waitlist!`)
  // Share the referral code
  showReferralCode(data.referral_code)
}

Double Opt-in Flow

When double opt-in is enabled for your waitlist:

User submits their email via the API
A confirmation email is sent automatically
User clicks the confirmation link in their email
User is added to the waitlist and redirected to the thank-you page
Welcome email is sent (if enabled)

Referral Tracking

When a user signs up through a referral:

Include the referrer's referral code in the metadata.referred_by field
The referrer gets credit once the new subscriber confirms (if double opt-in is enabled) or immediately (if disabled)
The new subscriber gets a unique referral code they can share

Referral Fraud Protection for API Users

By default, referral fraud detection is skipped for API sign-ups because the IP address seen by Waitlister is your server's IP, not the end user's. To enable fraud protection for API-sourced referrals, forward the end user's real IP address and (optionally) a device fingerprint:

metadata.client_ip — The end user's IP address. For best results, forward the value from your request headers (e.g. X-Forwarded-For, CF-Connecting-IP, or your framework's equivalent).
metadata.fingerprint — A client-side device fingerprint.

When either field is provided, Waitlister applies the same fraud detection signals used for form and landing page sign-ups, including IP deduplication, fingerprint matching, velocity checks, and self-referral detection. When neither is provided, API sign-ups work exactly as before with no fraud checks.

Rate Limits

See API Rate Limits for more information.

Documentation