The subscribers endpoints are the v1 surface of the customer API. List the people who joined a waitlist, or create a signup from your own server.
All requests require a Bearer key. See Authentication.
List subscribers
GET https://api.getqueueup.com/v1/api/waitlists/{waitlist_id}/subscribersRequired scope: subscribers:read.
Returns paginated subscribers for the named waitlist. Use this to sync to a CRM, build your own analytics dashboard, or back up data periodically.
Query params
| Param | Type | Default | Notes |
|---|---|---|---|
page | integer | 1 | 1-indexed. |
limit | integer | 25 | Max 200. |
q | string | empty | Substring match against the email address (case-insensitive). |
Response
200 OK{
"items": [
{
"id": "8401",
"email": "[email protected]",
"joined_at": "2026-05-03T18:30:12Z",
"position": 42,
"referral_code": "K7M9PX",
"referral_count": 3
}
],
"total": 1024,
"page": 1,
"limit": 25
}| Field | Type | Notes |
|---|---|---|
id | string | Stable id for this subscriber. |
email | string | Display case preserved as submitted. |
joined_at | string | RFC 3339 timestamp. |
position | integer | Current spot in line, computed live (not stored). |
referral_code | string | The 6-character code minted for this subscriber. Empty when referrals are off on the waitlist. |
referral_count | integer | How many other subscribers used this person’s code. |
The hosted-status capability token is not included; use the panel’s Export CSV if you need it.
Errors
| Status | When |
|---|---|
403 insufficient_scope | Key doesn’t carry subscribers:read. |
404 not_found | Waitlist doesn’t exist or is archived. |
Create a subscriber
POST https://api.getqueueup.com/v1/api/waitlists/{waitlist_id}/subscribersRequired scope: subscribers:write.
Server-to-server signup. Use this when your own backend already knows it has a real user (e.g. a confirmed signup on your site, a row imported from another system).
This path skips three of the public endpoint’s anti-abuse checks: Origin allowlist, Challenge, and Proof of Work. The Bearer key already proves tenant identity, so requiring the visitor’s browser to solve a puzzle would be ceremony for ceremony’s sake. Other gates the operator turned on still apply: per-email throttle, MX verification, disposable-email blocklist, and (with the caveat below) geo restrictions.
Request body
{
"email": "[email protected]",
"referral_code": "K7M9PX",
"client_country": "DE"
}| Field | Type | Required | Notes |
|---|---|---|---|
email | string | yes | RFC 5322 syntax. Normalised server-side. |
referral_code | string | no | Forwarded to the referral attribution system. Invalid or cross-waitlist codes are silently ignored. |
client_country | string | no | ISO 3166-1 alpha-2. The geo gate uses this when set. Without it, the gate falls back to the country of the immediate request peer (your server, on a server-to-server call), which is rarely what you want. Pass the visitor’s country here if geo rules are configured on the waitlist. |
Response
202 Accepted{
"status": "accepted",
"status_token": "9b1f4a32b...",
"referral_code": "Q4M6PX",
"status_url": "https://app.getqueueup.com/s/9b1f4a32b..."
}The shape mirrors the public Subscribe endpoint so a single client can drive both. Empty status_token and referral_code mean the waitlist has referrals turned off.
Errors
| Status | When |
|---|---|
400 invalid_email | Email failed RFC 5322 validation. |
403 insufficient_scope | Key doesn’t carry subscribers:write. |
404 not_found | Waitlist doesn’t exist or is archived. |
429 rate_limit_exceeded | Per-key throttle exceeded. |