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

ParameterDescription
waitlist-keyYour unique waitlist key, found in your waitlist settings

Query Parameters

ParameterTypeDefaultDescription
limitNumber20Number of results to return (max 100)
pageNumber1Page number for pagination
sort_byString'date'Field to sort by (see options below)
sort_dirString'desc'Sort direction: 'asc' or 'desc'

Supported Sort Fields

FieldDescription
positionSubscriber's position in the waitlist
pointsSubscriber's referral points
dateDate the subscriber joined
referral_countNumber of successful referrals
emailSubscriber'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

FieldTypeDescription
successBooleanAlways true for successful responses
data.subscribersArrayList of subscriber objects
data.totalNumberTotal number of subscribers matching the query
data.pageNumberCurrent page number
data.limitNumberNumber of results per page
data.pagesNumberTotal number of pages available

Subscriber Object Fields

FieldTypeDescription
idStringUnique identifier for the subscriber
emailStringSubscriber's email address
deliverabilityStringEmail deliverability status
nameStringSubscriber's name (if provided)
phoneStringSubscriber's phone number (if provided)
positionNumberSubscriber's position in the waitlist
pointsNumberSubscriber's points
referral_codeStringSubscriber's unique referral code
referred_byStringReferral code of the user who referred this subscriber
referral_countNumberNumber of successful referrals made by this subscriber
referring_domainStringDomain that referred the subscriber
countryStringSubscriber's country based on IP
cityStringSubscriber's city based on IP
timezoneStringSubscriber's timezone based on IP
joined_withStringHow the subscriber was added (api, form, etc.)
joined_atNumberTimestamp 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.

  1. Start with page 1 and a reasonable limit (e.g., 20)
  2. Use the total and pages values to determine how many more requests you need
  3. 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

PlanRate Limit
Pro60 requests per minute
Scale120 requests per minute

See API Rate Limits for more information.

Get started for free

Start collecting sign ups for your product launch in minutes — no coding required.