Onboarding Flows

Onboarding flows define step-by-step experiences for new users. Track completion rates and optimize your first-time user experience.

How it works

Admin creates an onboarding flow with ordered steps
The SDK fetches the active flow and the user's current position
As users advance through steps, progress is tracked automatically
Analytics show start, completion, and skip rates per flow

MCP tools

Tool	Description
`amba_onboarding_create`	Create an onboarding flow with steps
`amba_onboarding_get_stats`	Get completion statistics

Example

Agent: "Create a welcome onboarding flow"

amba_onboarding_create({
  project_id: "proj_xxx",
  name: "Welcome Flow",
  steps: [
    { id: "welcome",       title: "Welcome",      description: "Welcome to the app!",           type: "welcome" },
    { id: "notifications", title: "Stay Updated",  description: "Enable push notifications",     type: "permission", config: { permission: "push" } },
    { id: "personalize",   title: "Personalize",   description: "Tell us about yourself",        type: "personalization" },
    { id: "tour",          title: "Quick Tour",    description: "See what you can do",           type: "feature_tour" }
  ]
})

SDK usage

The SDK talks to the active flow without requiring a flow ID. Amba resolves the primary flow automatically — the oldest active flow for the project.

const amba = new Amba(config);
 
// Get current status (pre-start, in-progress, or completed)
const status = await amba.onboarding.getStatus();
// {
//   flow_id: "...",
//   flow_name: "Welcome Flow",
//   current_step: "welcome",
//   completed_steps: [],
//   remaining_steps: ["welcome", "notifications", "personalize", "tour"],
//   completed: false,
//   status: "not_started"
// }
 
// Advance to the next step (auto-starts if not yet started)
// Optionally pass answers collected during the current step.
const next = await amba.onboarding.nextStep({ answers: { name: 'Alex' } });
 
// Skip the flow entirely
await amba.onboarding.skipStep();
 
// Mark the flow complete (optionally with a final payload)
await amba.onboarding.complete({ final_answers: { agreed_to_terms: true } });

nextStep() is safe to call before the user has explicitly started the flow — it creates the progress row and advances past the first step in one call. Calling it again after the flow is already completed is idempotent and returns the current status unchanged.

Client API reference

These are the paths the SDK calls. You only need them if you are building a custom integration or calling the API directly.

Method	Path	Description
`GET`	`/client/onboarding/status`	Get status for the primary active flow
`POST`	`/client/onboarding/next`	Advance to the next step; body: `{ answers?: object }`
`POST`	`/client/onboarding/skip`	Skip the flow
`POST`	`/client/onboarding/complete`	Mark complete; body: `{ final_answers?: object }`

Status shape

{
  "data": {
    "flow_id": "uuid",
    "flow_name": "Welcome Flow",
    "current_step": "notifications",
    "completed_steps": ["welcome"],
    "remaining_steps": ["notifications", "personalize", "tour"],
    "completed": false,
    "completed_at": null,
    "status": "in_progress"
  }
}

status is one of not_started, in_progress, completed, or skipped.

Error codes

Code	Status	Meaning
`NO_ACTIVE_ONBOARDING_FLOW`	404	No active flow configured for this project
`NOT_STARTED`	404	User has not started the flow (skip / complete)
`FLOW_SKIPPED`	409	Flow was skipped; cannot advance
`INVALID_ANSWERS`	400	`answers` or `final_answers` is not a plain object

Advanced — multiple flows

If your project has more than one active flow, the SDK always resolves the oldest active flow (by creation date) as the primary. To work with a specific flow, use the explicit flow ID routes:

Method	Path	Description
`POST`	`/client/onboarding/:flowId/start`	Start a specific flow
`POST`	`/client/onboarding/:flowId/advance`	Advance within a specific flow
`POST`	`/client/onboarding/:flowId/skip`	Skip a specific flow
`POST`	`/client/onboarding/:flowId/complete`	Complete a specific flow

On this page