API Reference / Endpoints

Get Subscriber

The Get Subscriber endpoint allows you to retrieve detailed information about a specific subscriber by either their unique ID or email address. This is useful for looking up individual subscriber details or verifying subscriber status.

Endpoint Details

  • URL: https://waitlister.me/api/v1/waitlist/{waitlist-key}/subscribers/{id-or-email}
  • 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
id-or-emailEither the subscriber's unique ID or their email address

Response

Success Response 200

{
  "success": true,
  "data": {
    "subscriber": {
      "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,
      "metadata": {
        "company": "Acme Inc",
        "role": "Developer",
        "custom_field": "custom value"
      },
      "referring_domain": "twitter.com",
      "country": "US",
      "city": "San Francisco",
      "timezone": "America/Los_Angeles",
      "joined_with": "api",
      "joined_at": 1682345678901
    }
  }
}

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
metadataObjectCustom fields and additional information about the 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

Not Found 404

{
  "statusCode": 404,
  "error": "Not Found",
  "message": "Subscriber not found"
}

Access Denied 403

{
  "statusCode": 403,
  "error": "Forbidden",
  "message": "Access denied to this subscriber"
}

Examples

Get Subscriber by ID

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

Get Subscriber by Email

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

Implementation Notes

Using Email vs ID

  • ID Lookup: More efficient when you already know the subscriber's unique ID
  • Email Lookup: More convenient when integrating with systems that track users by email

Note that email lookups are case-insensitive. The email address is normalized to lowercase before lookup.

Metadata Usage

The metadata object contains any custom fields you've collected or stored with the subscriber. This can include:

  • Custom form field values
  • Integration data from other systems
  • Tracking parameters
  • User preferences or characteristics

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.