Onboarding state
Onboarding
Onboarding state
Read the authenticated user’s onboarding progress (resume oracle).
GET
Onboarding state
Overview
Returns the authenticated user’s current position in the four-step onboarding flow. The mobile client calls this on app launch and after every disconnect to know where to resume the user — it is the resume oracle for the onboarding state machine.currentStep is the step the user is currently expected to submit next. Once onboardingStatus becomes COMPLETE, currentStep is set to null and all onboarding step endpoints return 409 STATE_CONFLICT. From that point further edits go through the post-onboarding surfaces (/current-home/me, /preferences/me).
Authentication
Bearer <accessToken> required. Scope: user.
Path parameters
None.Query parameters
None.Request body
None.Response — 200 OK
| Field | Type | Allowed values | Example |
|---|---|---|---|
onboardingStatus | enum | IN_PROGRESS, COMPLETE | IN_PROGRESS |
currentStep | integer | null | 1, 2, 3, 4, or null when status is COMPLETE | 3 |
tenancyStatus | enum | NOT_SUBMITTED, PENDING, APPROVED, REJECTED | PENDING |
Example response
Error responses
| Status | Code | Meaning |
|---|---|---|
| 401 | UNAUTHENTICATED | Missing, malformed, or expired access token. |
| 404 | NOT_FOUND | User not found (token references a deleted account). |
Example error — 401
Side effects
None — this is a pure read.See also
- Onboarding state machine — the full lifecycle diagram.
- Step 1 — tenancy
- Step 2 — current home
- Step 3 — photos
- Step 3 — description
- Step 4 — desired home