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

Parameter	Description
`waitlist-key`	Your unique waitlist key, found in your waitlist settings
`id-or-email`	Either the subscriber's unique ID or their email address

Response

Success Response `200`

{
  "success": true,
  "data": {
    "subscriber": {
      "id": "xyzABC123",
      "email": "user@example.com",
      "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

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
`metadata`	Object	Custom fields and additional information about the 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

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

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

See API Rate Limits for more information.

Get Subscriber

Get started for free