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.
Want the full picture in one fetch? The one-page integration guide covers every path with copy-paste code · OpenAPI spec · SDK: npm install waitlister
Endpoint Details
- URL:
https://waitlister.me/api/v1/waitlist/{waitlist-key}/subscribers/{id-or-email} - Method:
GET
Request
Headers
code
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
json
{
"success": true,
"data": {
"subscriber": {
"id": "xyzABC123",
"email": "user@example.com",
"deliverability": "unconfirmed",
"name": "John Doe",
"phone": "+1234567890",
"position": 42,
"inflated_position": 42,
"points": 150,
"referral_code": "happy-star-4f3d",
"referred_by": "cool-moon-9e2a",
"referral_count": 3,
"sign_up_token": "abc123xyz",
"thank_you_url": "https://waitlister.me/thank-you/your-waitlist-key/abc123xyz",
"metadata": {
"company": "Acme Inc",
"role": "Developer",
"custom_field": "custom value"
},
"referring_domain": "twitter.com",
"ip_address": "192.168.1.1",
"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 real position in the waitlist |
inflated_position | Number | Public-facing position with any position inflation offset applied |
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 |
sign_up_token | String | Unique token for this subscriber |
thank_you_url | String | URL to the subscriber's thank you page |
metadata | Object | Custom fields and additional information about the subscriber |
referring_domain | String | Domain that referred the subscriber |
ip_address | String | Subscriber's IP address |
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
json
{
"statusCode": 404,
"error": "Not Found",
"message": "Subscriber not found"
}
Access Denied 403
json
{
"statusCode": 403,
"error": "Forbidden",
"message": "Access denied to this subscriber"
}
Examples
Get Subscriber by ID
bash
curl "https://waitlister.me/api/v1/waitlist/your-waitlist-key/subscribers/xyzABC123" \
-H "X-Api-Key: your-api-key"
Get Subscriber by Email
bash
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
See API Rate Limits for more information.