> ## Documentation Index
> Fetch the complete documentation index at: https://docs.sumvin.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Onboarding state machine

> The states a user passes through from creation to fully onboarded.

# Onboarding state machine

A Sumvin user moves through a defined sequence of onboarding steps. Each step represents work the user has to complete (or that the platform chooses to skip) before they can be considered fully onboarded. The state machine is linear, idempotent, and observable through the Platform API.

## The steps, in order

```text theme={null}
created
  → phone_verification
  → kyc_verification
  → byo_safe        (cohort: BYO_SAFE)
  → safe_deploy     (cohort: USER_SIGNED_DEPLOY)
  → open_banking
  → card_setup
  → feature_selection
  → complete
```

Any gated step can be skipped per user via platform configuration — for example, an integration that doesn't issue cards would skip `card_setup` and `open_banking`. Steps that are skipped still appear in the state machine, marked as skipped rather than incomplete.

`kyc_verification` is the exception: it cannot be skipped per partner. The SIS `kyc` feature is always-required (see [Always-required features](/dashboard/features#always-required-features)). What the partner *can* configure is the verification *mode* — surfaced on the step's `meta.kyc_mode` field as `websdk`, `hybrid`, or `document_only` — which the resolver picks per-environment with a Statsig dynamic-config fallback (`kyc_verification_mode`, default `websdk`).

### Wallet-cohort steps

`byo_safe` and `safe_deploy` are mutually exclusive — a single user is in **one** of three cohorts based on the SIS environment's feature flags:

| `AI_AGENT` | `USER_SIGNED_DEPLOY` | What runs                            | Description                                                                    |
| ---------- | -------------------- | ------------------------------------ | ------------------------------------------------------------------------------ |
| enabled    | disabled             | neither — agent-signed Safe creation | Sumvin's signing service deploys the Safe with an agent signer attached.       |
| disabled   | enabled              | `safe_deploy`                        | The user signs an ERC-4337 UserOp themselves; Sumvin sponsors gas via Pimlico. |
| disabled   | disabled             | `byo_safe`                           | The user submits the address of a Safe they already control on-chain.          |

Both flags enabled at the same time is rejected at the SIS feature-write API with **`SIS-409-008` (Feature Mutex Violation)** — see [SIS feature mutex](/dashboard/features). Users without an `org_id` skip both steps.

## Who drives transitions

| Driver      | Transition                                                                                                                                                                                                                                                             |
| ----------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Partner** | Submits the current step when the user finishes it                                                                                                                                                                                                                     |
| **Sumvin**  | Advances automatically on <Tooltip headline="KYC" tip="Know Your Customer — identity verification that feeds attestation claims onto credentials." cta="Glossary →" href="/glossary">KYC</Tooltip> approval, Safe deployment, and other asynchronous completion events |

Partner-driven transition:

* [`POST /v0/user/me/onboarding/steps`](/api-reference/user/submit-onboarding-step-route) — Submit the completed step.

Submitting the same step twice is a no-op, not an error — onboarding tolerates retries. A submission that enqueues background provisioning work (creation flow, KYC completion) returns `202 Accepted`; purely synchronous transitions return `200 OK`.

## How to observe the current state

```bash theme={null}
curl /v0/user/me/onboarding/steps \
  -H "x-juno-jwt: <token>" \
  -H "x-juno-orgid: <your-org-id>"
```

The response returns the current step, every step's status, and a boolean `is_complete`. When `is_complete` is `true`, `current_step` is `"complete"`.

## See also

* [Onboarding guide](/guides/onboarding) — full flow with code samples
* [KYC guide](/guides/kyc) — how `kyc_verification` works
* [Wallets guide](/guides/wallets) — async Safe creation that blocks onboarding

## Referenced from

* [Introduction](/introduction)
* [Quickstart](/quickstart)
* [App developer persona](/overview/personas/app-developer)