API Reference / Endpoints
List Subscribers
The List Subscribers endpoint allows you to retrieve a paginated list of subscribers from your waitlist. This is useful for integrating Waitlister with your own admin dashboard or CRM system.
- URL:
https://waitlister.me/api/v1/waitlist/{waitlist-key}/subscribers - Method:
GET - Required Plan: Pro or Scale
X-Api-Key: your-api-key
| Parameter | Description |
|---|
waitlist-key | Your unique waitlist key, found in your waitlist settings |
| Parameter | Type | Default | Description |
|---|
limit | Number | 20 | Number of results to return (max 100) |
page | Number | 1 | Page number for pagination |
sort_by | String | 'date' | Field to sort by (see options below) |
sort_dir | String | 'desc' | Sort direction: 'asc' or 'desc' |
| Field | Description |
|---|
position | Subscriber's position in the waitlist |
points | Subscriber's referral points |
date | Date the subscriber joined |
referral_count | Number of successful referrals |
email | Subscriber's email address |
{
"success": true,
"data": {
"subscribers": [
{
"id": "xyzABC123",
"email": "[email protected]",
"deliverability": "unconfirmed",
"name": "John Doe",
"phone": "+1234567890",
"position": 42,
"points": 150,
"referral_code": "happy-star-4f3d",
"referred_by": "cool-moon-9e2a",
"referral_count": 3,
"referring_domain": "twitter.com",
"country": "US",
"city": "San Francisco",
"timezone": "America/Los_Angeles",
"joined_with": "api",
"joined_at": 1682345678901
},
// Additional subscribers...
],
"total": 245,
"page": 1,
"limit": 20,
"pages": 13
}
}
| Field | Type | Description |
|---|
success | Boolean | Always true for successful responses |
data.subscribers | Array | List of subscriber objects |
data.total | Number | Total number of subscribers matching the query |
data.page | Number | Current page number |
data.limit | Number | Number of results per page |
data.pages | Number | Total number of pages available |
| Field | Type | Description |
|---|
id | String | Unique identifier for the subscriber |
email | String | Subscriber's email address |
deliverability | String | Email deliverability status |
name | String | Subscriber's name (if provided) |
phone | String | Subscriber's phone number (if provided) |
position | Number | Subscriber's position in the waitlist |
points | Number | Subscriber's points |
referral_code | String | Subscriber's unique referral code |
referred_by | String | Referral code of the user who referred this subscriber |
referral_count | Number | Number of successful referrals made by this subscriber |
referring_domain | String | Domain that referred the subscriber |
country | String | Subscriber's country based on IP |
city | String | Subscriber's city based on IP |
timezone | String | Subscriber's timezone based on IP |
joined_with | String | How the subscriber was added (api, form, etc.) |
joined_at | Number | Timestamp when the subscriber joined (milliseconds since epoch) |
{
"statusCode": 401,
"error": "Unauthorized",
"message": "Invalid API key"
}
{
"statusCode": 429,
"error": "Too Many Requests",
"message": "Rate limit exceeded. 60 requests allowed per minute."
}
curl "https://waitlister.me/api/v1/waitlist/your-waitlist-key/subscribers" \
-H "X-Api-Key: your-api-key"
curl "https://waitlister.me/api/v1/waitlist/your-waitlist-key/subscribers?limit=50&page=2&sort_by=points&sort_dir=desc" \
-H "X-Api-Key: your-api-key"
When your waitlist has many subscribers, use pagination to efficiently retrieve them.
- Start with page 1 and a reasonable limit (e.g., 20)
- Use the
total and pages values to determine how many more requests you need - Increment the page parameter for each subsequent request
Use sorting to organize the results according to your needs.
- Sort by
position to see who's first in line - Sort by
referral_count or points to identify your most engaged users - Sort by
date to see the most recent sign-ups
| Plan | Rate Limit |
|---|
| Pro | 60 requests per minute |
| Scale | 120 requests per minute |
See API Rate Limits for more information.
