# GetWait
> GetWait is a waitlist API: collect emails, confirm them (double opt-in), rank people by position, and reward referrals. Use it from a browser with a publishable key, or from a server with a secret key. Base URL: https://getwait.dev (all routes under /api/v1).
You are an AI coding assistant adding a waitlist signup form to the user's project. Follow "Implementation steps" below. Do not invent API shapes: everything you need is on this page.
## Before you start (ask the user if missing)
1. A **waitlist ID** (UUID). Created in the GetWait dashboard under the project.
2. A **publishable key** `gw_pk_live_...` (or `gw_pk_test_...`). Created in the dashboard (project page, "Create website key"). The site's origin (e.g. https://mysite.com, http://localhost:3000) must be in the key's allowed origins, exact match, no wildcards.
Never use a secret key (`gw_sk_...`) in browser code, client bundles, or anything committed to git. Publishable keys are safe in client code.
## Keys
| Key | Format | Where | Can |
| ----------- | ----------- | ------------ | ------------------------------------------- |
| Publishable | `gw_pk_...` | Browser | join, look up status, leaderboard |
| Secret | `gw_sk_...` | Servers only | everything (waitlists, signups, webhooks) |
Publishable keys are checked by the browser `Origin` header, so joins from Node/SSR with a `gw_pk_` key are refused. Call join from the browser, or use a secret key on the server.
## Implementation steps
1. Put the keys in env vars (e.g. `NEXT_PUBLIC_GETWAIT_PUBLISHABLE_KEY`, `NEXT_PUBLIC_GETWAIT_WAITLIST_ID`, or the framework equivalent such as `VITE_...`). Never hardcode a secret key.
2. Install: `npm i @getwait/waitlist` (typed client, zero deps) and, for React, `npm i @getwait/react` (headless hook, you bring the markup). Use the project's package manager.
3. Build the form matching the project's existing styling and components. Email input, submit button, loading state, error message, success state showing position and referral code.
4. Read `?ref=` from the URL and pass it as `ref` when joining (referrals).
5. Handle errors by type (see below). Show friendly text, not raw `error.message`.
6. Test with a real address on a domain with a mail server. `example.com` and disposable domains are rejected (`abuse_blocked`).
### React
```tsx
import { useState, type FormEvent } from "react"
import { useReferralFromUrl, useWaitlist, WaitlistProvider } from "@getwait/react"
export function Signup() {
return (
)
}
function JoinForm() {
const { join, status, data, error, reset } = useWaitlist()
const ref = useReferralFromUrl()
const [email, setEmail] = useState("")
function onSubmit(event: FormEvent) {
event.preventDefault()
void join(ref ? { email, ref } : { email })
}
if (status === "success" && data) {
return (
You are #{data.position} on the list.
Share ?ref={data.referralCode} to move up.
)
}
return (
)
}
```
`useWaitlist()` returns `{ join, status: "idle" | "submitting" | "success" | "error", data: { position, referralCode, status } | null, error, reset }`. `join` never rejects. `WaitlistProvider` with a `gw_sk_` key throws. Put it in a client component (`"use client"` in Next.js App Router).
### Any framework (SDK only)
```ts
import { createClient } from "@getwait/waitlist"
const client = createClient({ apiKey: "gw_pk_live_..." }) // publishable key, browser
const { position, referralCode, status, created } = await client
.waitlist("WAITLIST_ID")
.join({
email: "ada@gmail.com",
ref: new URLSearchParams(location.search).get("ref") ?? undefined,
})
```
Other client methods (publishable key OK): `.status(referralCode)` returns `{ position, status, referralCode, referralCount }`; `.leaderboard({ limit })` returns `[{ rank, referralCount, name }]`. Secret key only: `client.waitlists.create({ name })`, `client.signups.list/get/delete`, `client.webhooks.create`.
### No SDK (plain fetch)
```js
const res = await fetch("https://getwait.dev/api/v1/waitlists/WAITLIST_ID/signups", {
method: "POST",
headers: {
Authorization: "Bearer gw_pk_live_...",
"Content-Type": "application/json",
},
body: JSON.stringify({ email, ref }), // ref optional
})
const body = await res.json() // 201 new or 200 existing: { id, position, referralCode, status }
```
## Join semantics
- `POST /api/v1/waitlists/:id/signups`. Body: `email` (required), `ref` (optional referral code), `source` (optional: `utm_source`, `utm_medium`, `utm_campaign`, `utm_term`, `utm_content`, `referrer`; other keys are a 422).
- Response `{ id, position, referralCode, status }`. `201` new signup, `200` already on the list (SDK: `created: false`).
- **Idempotent by email**: retrying is always safe. `A.b+x@gmail.com` and `ab@gmail.com` are the same person.
- `status`: `pending` (email not confirmed yet), `verified`, `removed`.
- **Double opt-in is on by default**: the person gets a confirmation email; tell them to check their inbox. Show "check your email" copy, not "you're in".
- **Position** is a 1-based rank by join time, computed on read. **Referral code** is 8 chars. A referral only counts once the referred person confirms their email.
- Share link format: `https://yoursite.com/?ref=`.
## Errors
Every failure is `{ error: { code, message, requestId, details? } }`. Branch on `code`; always keep a default branch.
| Status | code | Do |
| ------ | -------------------- | ------------------------------------------------------- |
| 401 | `unauthorized` | Key missing/wrong/revoked. |
| 402 | `plan_limit_reached` | Free plan cap (2 waitlists, 1,000 signups each). |
| 403 | `forbidden` | Origin not in key's allowed origins, or secret-only route. |
| 404 | `not_found` | Wrong waitlist ID. |
| 409 | `waitlist_archived` | Waitlist no longer accepts joins. |
| 422 | `validation_failed` | Bad email; `details.issues[]` per field. |
| 422 | `abuse_blocked` | Captcha, disposable or undeliverable email. Show a generic failure. |
| 429 | `rate_limited` | Wait `Retry-After` seconds. Join: 10/min per IP. |
SDK classes (import from `@getwait/waitlist`): `ValidationError` (`.issues`), `AbuseBlockedError`, `AuthError`, `NotFoundError`, `PlanLimitError`, `RateLimitError` (`.retryAfter`), `NetworkError`, `TimeoutError`, `SecretKeyRequiredError`. All carry `.code`, `.status`, `.requestId`. The SDK auto-retries network errors, timeouts, 429 and 5xx.
## Common mistakes
- Using `gw_sk_` in client code. Use `gw_pk_`.
- Forgetting to add the site origin (including `http://localhost:PORT` for dev) to the publishable key's allowed origins, giving 403 `forbidden`.
- Calling join with a `gw_pk_` key from server code or SSR. Call it from the browser.
- Calling join from a server for many visitors with a secret key: all share the server IP and hit the 10/min join limit.
- Telling the user "you're in" before email confirmation.
- Testing with `example.com` or throwaway addresses (`abuse_blocked`).
## Server-side (optional)
Use a secret key (`GETWAIT_SECRET_KEY`, never in the client) to create waitlists, list/export signups, and receive webhooks. Webhook events: `signup.created`, `signup.verified`, `referral.converted`. Verify the `GetWait-Signature` header over the raw body:
```ts
import { verifyWebhookSignature } from "@getwait/waitlist"
const rawBody = await request.text()
const result = await verifyWebhookSignature({
payload: rawBody,
header: request.headers.get("GetWait-Signature"),
secret: process.env.GETWAIT_WEBHOOK_SECRET!,
})
if (!result.ok) return new Response(null, { status: 400 })
```
Delivery is at-least-once: deduplicate on `event.id`.
## Docs
- Packages: `@getwait/react` (React hook), `@getwait/waitlist` (typed client). If install fails because a package is not published yet, use the plain fetch example above.