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.

Endpoint Details

URL: https://waitlister.me/api/v1/waitlist/{waitlist-key}/subscribers
Method: GET
Required Plan: Pro or Scale

Request

Headers

X-Api-Key: your-api-key

Path Parameters

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

Query Parameters

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'

Supported Sort Fields

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

Response

Success Response `200`

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

Response Fields

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

Subscriber Object Fields

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)

Error Responses

Unauthorized `401`

{
  "statusCode": 401,
  "error": "Unauthorized",
  "message": "Invalid API key"
}

Rate Limit Exceeded `429`

{
  "statusCode": 429,
  "error": "Too Many Requests",
  "message": "Rate limit exceeded. 60 requests allowed per minute."
}

Examples

Basic Request

curl "https://waitlister.me/api/v1/waitlist/your-waitlist-key/subscribers" \
  -H "X-Api-Key: your-api-key"

With Pagination and Sorting

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"

Implementation Notes

Pagination

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

Sorting

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

Rate Limits

Plan	Rate Limit
Pro	60 requests per minute
Scale	120 requests per minute

See API Rate Limits for more information.

Documentation