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.
- URL:
https://waitlister.me/api/v1/waitlist/{waitlist-key}/sign-up - Method:
POST - Required Plan: Pro or Scale
Content-Type: application/json
X-Api-Key: your-api-key
| Parameter | Description |
|---|
waitlist-key | Your unique waitlist key, found in your waitlist settings |
{
"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"
}
}
| Field | Type | Description |
|---|
email | String | The subscriber's email address |
| 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 |
{
"success": true,
"is_new_sign_up": true,
"message": "Successfully signed up",
"position": 42,
"referral_code": "happy-star-4f3d",
"redirect_url": "https://waitlister.me/thank-you/waitlist-key/token"
}
| 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 |
redirect_url | String | URL to Waitlister's pre-built thank you page for this subscriber |
{
"success": false,
"error": {
"code": "invalid_email",
"message": "The email address is invalid."
}
}
| Error Code | Description |
|---|
invalid_email | The provided email address is invalid |
missing_required_field | A required field is missing from the request |
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"
}
}'
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) - Consider adding social sharing options for the referral link
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
| Plan | Rate Limit |
|---|
| Pro | 60 requests per minute |
| Scale | 120 requests per minute |
See API Rate Limits for more information.