/v1/workspaces/{workspace_id}/waitlists/{waitlist_id}/invite-wavesAuthInvite 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 · uuidId of the workspace.
waitlist_id*string · uuidId of the waitlist.
Headers
Idempotency-KeystringIdempotency key (24 h). A retry with the same key and body returns the first response instead of starting a second wave.
Request body
size*integerHow 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_slugstringAuth app to invite into (`auth`). Default: the app linked in the Waitlist settings.
Example: "acme-app"
send_emailbooleanEmail each invitee (the approved template, with the invite link or access code). Default true.
Example: true
run_atstring · date-timeWhen to run. Omit to run now.
Example: "2026-11-24T09:00:00Z"
repeat_every_hoursintegerRun again every N hours (a drip, e.g. 24 for "100 a day") until canceled.
Example: 24
api_keystringScheduled `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 · uuidWave id.
waitlist_id*string · uuidThe waitlist.
size*integerPeople per run.
method*object`auth` (Auth app invites) or `code` (access codes).
app_slug*stringAuth app (`auth`).
send_email*booleanWhether 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-timeWhen it runs next (scheduled waves); null otherwise.
repeat_every_hours*integerRepeats every N hours; null runs once.
runs*integerRuns so far.
invited_total*integerInvited across all runs.
failed_total*integerFailed across all runs.
last_run_at*string · date-timeWhen it last ran.
last_error*stringThe last failure, if any.
has_api_key*booleanWhether an API key is saved for scheduled `auth` runs (never returned).
created_by*string · uuidWho created it (platform user or API key subject).
created_at*string · date-timeWhen it was created.
updated_at*string · date-timeWhen 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"
}