Waitlist API reference

Waitlist API · Waitlist-Invites

post/v1/workspaces/{workspace_id}/waitlists/{waitlist_id}/invite-wavesAuth

Invite the next N in line, now or on a schedule

Picks the next `size` entries by place in line (referral boosts included) that are `pending` or `approved` and not invited yet, approves the pending ones, and invites each: into your Auth app (`auth`) or with a single-use access code (`code`), emailing them unless `send_email: false`. Without `run_at` it starts now and runs in the background (GET the wave to follow it). With `run_at` and/or `repeat_every_hours` it is scheduled; a repeating wave invites the next `size` every N hours until canceled. A scheduled `auth` wave needs `api_key` (or call with an API key).

Path parameters

workspace_id*string · uuid

Id of the workspace.

waitlist_id*string · uuid

Id of the waitlist.

Headers

Idempotency-Keystring

Idempotency key (24 h). A retry with the same key and body returns the first response instead of starting a second wave.

Request body

size*integer

How many to invite: the next N in line who have not been invited yet.

Example: 100

method*object

`auth`: an invite into your Auth app (as invite-to-app). `code`: a single-use access code by email, for an app that is not on Auth; check it with `POST …/access-codes/redeem`.

Example: "auth"

app_slugstring

Auth app to invite into (`auth`). Default: the app linked in the Waitlist settings.

Example: "acme-app"

send_emailboolean

Email each invitee (the approved template, with the invite link or access code). Default true.

Example: true

run_atstring · date-time

When to run. Omit to run now.

Example: "2026-11-24T09:00:00Z"

repeat_every_hoursinteger

Run again every N hours (a drip, e.g. 24 for "100 a day") until canceled.

Example: 24

api_keystring

Scheduled `auth` waves only: a workspace API key (`pcft_…`) that may invite into the Auth app, used when the wave runs. Write-only, stored encrypted, dropped when the wave ends. Not needed when you call with that API key.

Example: "pcft_live_…"

Response · 202 Started or scheduled.

id*string · uuid

Wave id.

waitlist_id*string · uuid

The waitlist.

size*integer

People per run.

method*object

`auth` (Auth app invites) or `code` (access codes).

app_slug*string

Auth app (`auth`).

send_email*boolean

Whether invitees are emailed.

status*object

`scheduled` waits for `next_run_at` (a repeating wave goes back to it after each run); `running`; `done`; `failed` (nothing could be invited, see `last_error`); `canceled`.

next_run_at*string · date-time

When it runs next (scheduled waves); null otherwise.

repeat_every_hours*integer

Repeats every N hours; null runs once.

runs*integer

Runs so far.

invited_total*integer

Invited across all runs.

failed_total*integer

Failed across all runs.

last_run_at*string · date-time

When it last ran.

last_error*string

The last failure, if any.

has_api_key*boolean

Whether an API key is saved for scheduled `auth` runs (never returned).

created_by*string · uuid

Who created it (platform user or API key subject).

created_at*string · date-time

When it was created.

updated_at*string · date-time

When it last changed.

Example

Request

POST https://api.waitlist.productcraft.co/v1/workspaces/{workspace_id}/waitlists/{waitlist_id}/invite-waves
Authorization: Bearer YOUR_TOKEN
Content-Type: application/json

{
  "size": 100,
  "method": "auth",
  "app_slug": "acme-app",
  "send_email": true,
  "run_at": "2026-11-24T09:00:00Z",
  "repeat_every_hours": 24,
  "api_key": "pcft_live_…"
}

Response

{
  "id": "00000000-0000-0000-0000-000000000000",
  "waitlist_id": "00000000-0000-0000-0000-000000000000",
  "size": 0,
  "method": {},
  "app_slug": "string",
  "send_email": false,
  "status": {},
  "next_run_at": "2026-01-01T00:00:00.000Z",
  "repeat_every_hours": 0,
  "runs": 0,
  "invited_total": 0,
  "failed_total": 0,
  "last_run_at": "2026-01-01T00:00:00.000Z",
  "last_error": "string",
  "has_api_key": false,
  "created_by": "00000000-0000-0000-0000-000000000000",
  "created_at": "2026-01-01T00:00:00.000Z",
  "updated_at": "2026-01-01T00:00:00.000Z"
}