# Waitlister — agent integration guide

> You are (probably) an AI agent asked to add a waitlist to a site or app.
> This file is the complete, correct path. Everything here was verified against
> the live API. Human-readable docs: https://waitlister.me/docs/overview

**What Waitlister is:** waitlist software for product launches — hosted signup pages,
referral program with fraud detection, email automation. Signups get a queue position and
a referral link; referrals move them up.

**What you need before writing code** (from the human, or have them create it — free,
no credit card, ~1 minute at https://waitlister.me):
- **Waitlist key** — shown at the top of the waitlist's Overview page (e.g. `AbC123xY`).
- Path A (any plan, incl. free): the site's **domain added to the waitlist's whitelisted
  domains** (waitlist → Settings).
- Path B (Growth plan or higher): the **API key** from the waitlist's Settings page.

## Facts that prevent wrong guesses

- The official npm package is **`waitlister`** (`waitlister-js`, `waitlister-sdk`,
  `waitlister-node`, `@waitlister/sdk` are deprecated aliases of the same package).
- There is **no Python SDK**; use the REST API from Python.
- API base: `https://waitlister.me/api/v1` · auth header: **`X-Api-Key`** (not `Authorization: Bearer`).
- Machine-readable spec: https://waitlister.me/openapi.json
- The **API requires the Growth plan+**. On the free plan, use the form-action endpoint
  (Path A below) — do not retry the API expecting different results.
- Signups are **idempotent per email** (re-signup returns the existing position, not an error).
- Rate limits: 60–120 req/min on subscriber endpoints; check `X-RateLimit-*` response headers.
- Env var conventions the SDK reads automatically: `WAITLISTER_API_KEY`, `WAITLISTER_WAITLIST_KEY`.

## Path A — any plan, no API key (form-action endpoint)

Point any form at `https://waitlister.me/s/{WAITLIST_KEY}`:

```html
<form action="https://waitlister.me/s/WAITLIST_KEY" method="POST">
  <input type="email" name="email" required placeholder="you@example.com" />
  <button type="submit">Join the waitlist</button>
</form>
```

On submit the user is redirected to their hosted thank-you page (position + referral link).
Optional fields: `name`, `phone`, `referred_by` (referrer's code); any other field is saved
as metadata. **The page's domain must be in the waitlist's whitelisted domains** or the
endpoint returns 403.

From server code (Node), same endpoint via the SDK — pass a whitelisted origin:

```js
import { signUpViaForm } from 'waitlister'
const { redirectUrl } = await signUpViaForm(process.env.WAITLISTER_WAITLIST_KEY, {
  email, origin: 'https://your-whitelisted-domain.com'
})
// send the user to redirectUrl
```

## Path B — Growth plan+, full API

```bash
npm install waitlister
```

```js
import { Waitlister } from 'waitlister'
const wl = new Waitlister() // reads WAITLISTER_API_KEY + WAITLISTER_WAITLIST_KEY

const r = await wl.signUp({ email: 'user@example.com', name: 'Ada' })
// r.position, r.referral_code, r.redirect_url (hosted thank-you page)

const page = await wl.subscribers.list({ limit: 100 })          // paginated
const sub  = await wl.subscribers.get('user@example.com')        // by email or id
await wl.subscribers.update('user@example.com', { points: 500 }) // moves queue position
```

Referral loop: put `r.referral_code` in share links as `?ref=<code>`; pass incoming codes
back as `referredBy` on signup. Waitlister scores points, reorders positions, and runs
fraud detection automatically.

REST without the SDK:

```bash
curl -X POST "https://waitlister.me/api/v1/waitlist/WAITLIST_KEY/sign-up" \
  -H "Content-Type: application/json" -H "X-Api-Key: API_KEY" \
  -d '{"email":"user@example.com"}'
```

## Webhooks (optional)

Waitlister POSTs `waitlist.signup_created` events, HMAC-SHA256-signed over the raw body
(`X-Webhook-Signature: sha256=<hex>`). Verify with the SDK:

```js
import { constructWebhookEvent } from 'waitlister'
const event = await constructWebhookEvent({
  payload: rawBody,                                  // RAW string, not re-serialized JSON
  signature: req.headers.get('x-webhook-signature'),
  secret: process.env.WAITLISTER_WEBHOOK_SECRET
})
```

## Verify your integration

1. Submit a real, deliverable email (validation rejects fake/test addresses).
2. Expect a thank-you redirect (Path A) or `success: true` + position (Path B).
3. The subscriber appears in the dashboard, or via `wl.subscribers.list()`.

## Links

- Docs: https://waitlister.me/docs/overview · API reference: https://waitlister.me/docs/api
- Raw markdown docs: append `.md` to any `/docs/` URL (e.g. https://waitlister.me/docs/api.md) — section pages use `/docs/<section>.md`, not `/docs/<section>/index.md`
- OpenAPI: https://waitlister.me/openapi.json · npm: https://www.npmjs.com/package/waitlister
- llms.txt: https://waitlister.me/llms.txt · Pricing: https://waitlister.me/pricing