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",
    "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.*`	Any	Any additional custom fields you want to store with the subscriber

Response

Success Response `200`

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

Success 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
`message`	String	A human-readable success message
`position`	Number	The subscriber's position in your waitlist
`referral_code`	String	The subscriber's unique referral code that they can share
`sign_up_token`	String	A unique token for this subscriber, used in the thank you page URL
`redirect_url`	String	URL to Waitlister's pre-built thank you page for this subscriber (includes the sign-up token)

Error Responses

Bad Request `400`

{
  "success": false,
  "error": {
    "code": "invalid_email",
    "message": "The email address is invalid."
  }
}

Common Error Codes

Error Code	Description
`invalid_email`	The provided email address is invalid
`missing_required_field`	A required field is missing from the request

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"
    }
  }'

Implementation Notes

Handling the Response

After a successful sign-up, you have two options:

Use Waitlister's thank you page:
- Redirect the user to the redirect_url returned in the response
- This page includes referral options
Use your own thank you page:
- Display your custom thank you message
- Include the subscriber's position (position) and referral code (referral_code)
- Optionally use the sign_up_token to construct a link back to the Waitlister thank you page
- Consider adding social sharing options for the referral link

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 for the new sign-up
The new subscriber gets a unique referral code they can share

Rate Limits

See API Rate Limits for more information.

Documentation