POST
Onboarding step 2 — current home

Overview

Submits the property details that describe the user’s current home. The server creates a current_homes document in status: DRAFT (1:1 with the user — a unique partial index on userId enforces “one listing per user”) and advances currentStep from 2 to 3. The listing stays DRAFT through the rest of onboarding. Photos are attached in step 3, the description in step 3 description, and the listing only becomes eligible for LIVE once onboarding completes AND tenancy is APPROVED — see POST /current-home/me/publish. rentMonthlyMinor is derived server-side from rent (weekly → amountMinor * 52 / 12 rounded to nearest pence; monthly → identity) and is used by the matching engine. Preconditions:
  • Onboarding is IN_PROGRESS and currentStep is 2 or later (step 1 completed).
Re-submission is an upsert: while onboarding is in progress, posting step 2 again (e.g. the user navigated Back from a later step and edited their details) updates the existing DRAFT listing in place. currentStep only advances 2 → 3 on the first submission — a re-submission never moves or regresses it.

Authentication

Bearer <accessToken> required. Scope: user.

Path parameters

None.

Query parameters

None.

Request body

Rent object

Example payload

Response — 200 OK

Returns the refreshed onboarding state (same shape as GET /onboarding/state).

Example response

Error responses

Example error — 409

Side effects

  • First submission: inserts a row into the current_homes collection with status: DRAFT, the supplied details, photos: [], description: "", and rentMonthlyMinor derived from rent; sets users.currentStep = 3.
  • Re-submission (onboarding in progress): updates the existing DRAFT row’s step-2 fields in place; photos, description, status, and currentStep are untouched.

See also

curl