API Reference

The Waitlio API allows you to programmatically access your waitlists. All API requests are authenticated using Bearer tokens and return JSON responses.

Base URL

All API endpoints are available at:

https://waitlio.com/api

Interactive Swagger Docs

You can explore and test endpoints in the Swagger UI:

https://waitlio.com/api-reference/swagger

Authentication

Every request to the Waitlio API must include a Bearer token in the Authorization header. You can create API tokens from your team's Settings > API Tokens page.

curl https://waitlio.com/api/waitlists \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Accept: application/json"

If the token is missing or invalid, the API returns a 401 Unauthorized response.

Endpoints

List Waitlists

Returns all waitlists belonging to the team associated with your API token.

GET /api/waitlists

Response

Returns an array of waitlist objects.

[
    {
        "uuid": "9e3a1b2c-4d5e-6f7a-8b9c-0d1e2f3a4b5c",
        "name": "My Waitlist",
        "description": "A description of the waitlist",
        "status": "active",
        "public_url": "https://my-waitlist.waitlio.com",
        "subscribers_count": 128,
        "verified_subscribers_count": 95,
        "pending_subscribers_count": 33
    }
]

Fields

Field	Type	Description
uuid	string	Unique identifier for the waitlist
name	string	Name of the waitlist
description	string | null	Description of the waitlist
status	string	Either active or paused
public_url	string	Public URL where users can sign up
subscribers_count	integer	Total number of subscribers
verified_subscribers_count	integer	Number of verified subscribers
pending_subscribers_count	integer	Number of pending (unverified) subscribers

Get Waitlist by UUID

Returns a single waitlist by UUID.

GET /api/waitlists/{waitlistUuid}

Update Waitlist General Information

Updates a waitlist's general information.

PUT /api/waitlists/{waitlistUuid}

List Waitlist Subscribers

Returns paginated subscribers for a waitlist.

GET /api/waitlists/{waitlistUuid}/subscribers

Query Parameters

Parameter	Type	Description
status	string	Optional filter: verified or pending
sort	string	Optional sort column: position or created_at (default: created_at)
direction	string	Optional direction: asc or desc (default: desc)
per_page	integer	Optional page size: 10, 25, 50, or 100 (default: 25)

List Waitlist Webhooks

Returns all webhooks for a waitlist.

GET /api/waitlists/{waitlistUuid}/webhooks

Create Waitlist Webhook

Creates a webhook for a waitlist.

POST /api/waitlists/{waitlistUuid}/webhooks

The create response includes the webhook secret. Store it securely because it is used to verify webhook signatures.

Code Examples

JavaScript (fetch)

const response = await fetch('https://waitlio.com/api/waitlists', {
    headers: {
        Authorization: 'Bearer YOUR_API_TOKEN',
        Accept: 'application/json',
    },
});

const waitlists = await response.json();
console.log(waitlists);

PHP (cURL)

$ch = curl_init("https://waitlio.com/api/waitlists");
curl_setopt_array($ch, [
    CURLOPT_HTTPHEADER => [
        "Authorization: Bearer YOUR_API_TOKEN",
        "Accept: application/json",
    ],
    CURLOPT_RETURNTRANSFER => true,
]);

$response = curl_exec($ch);
$waitlists = json_decode($response, true);

Rate Limiting

API requests are rate-limited to 60 requests per minute per token. When the limit is exceeded, the API returns a 429 Too Many Requests response.

Errors

The API uses standard HTTP status codes.

Status	Description
200	Success
401	Unauthorized - invalid or missing token
403	Forbidden - insufficient permissions
429	Too many requests - rate limit exceeded
500	Internal server error