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": "[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
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.