Docs

Onboarding Module

Multi-step onboarding flows with progress tracking, completion webhooks, and bot protection built in.

Overview

The Onboarding module lets you define multi-step flows via API. Each flow has a steps array — each step can be an info screen, form, or confirmation. Users progress through sessions step by step, with payloads accumulated at each stage. When a session completes, a webhook fires with the full payload. Turnstile captcha protects the first step, and a hidden honeypot field discards bots silently.

API Endpoints

Create a Flow

Define your onboarding flow with a name and a steps array. Each step has a type (info, form, confirm) and a localized label.

POST /v1/onboarding/flows
Authorization: Bearer nk_live_...

{
  "name": "New User Setup",
  "steps": [
    { "type": "info", "label": { "en": "Welcome", "de": "Willkommen" } },
    { "type": "form", "label": { "en": "Your details" } },
    { "type": "confirm", "label": { "en": "Review" } }
  ]
}

Start a Session

Start a new session for a flow. The first step requires a Turnstile token for bot protection. Sessions begin at step 0.

POST /v1/public/onboarding/flows/{flowId}/sessions
{
  "locale": "en",
  "turnstileToken": "..."
}

// Response:
{
  "id": "...",
  "flowId": "...",
  "currentStep": 0,
  "payload": {},
  "completedAt": null
}

Advance Steps

Submit step data with a PATCH call. The payload merges into the session. Each call advances currentStep by one.

PATCH /v1/public/onboarding/sessions/{sessionId}
{
  "payload": {
    "name": "Jane Doe",
    "email": "[email protected]"
  }
}

// Response:
{
  "id": "...",
  "currentStep": 1,
  "payload": { "name": "Jane Doe", "email": "[email protected]" },
  "completedAt": null
}

When currentStep reaches the total number of steps, the session is marked complete and a webhook fires.

Completion Webhooks

Configure webhook endpoints in the dashboard. When a session completes, the onboarding.completed event fires with the full session payload, including all accumulated step data. Use this to trigger account creation, send welcome emails, or start downstream workflows.

Turnstile Captcha

Turnstile is only verified on step 0 (session creation). Once a session exists, subsequent steps do not require captcha. This keeps bot protection strong while maintaining a smooth experience for legitimate users. In development mode, Turnstile verification is skippable.

FAQ