POST
Onboarding step 1 — tenancy

Overview

Submits the user’s tenancy verification details: the landlord name (or curated landlord id once the registry is populated in Phase 6), the document type, and a reference to a previously confirmed TENANCY_DOC upload. The server creates a tenancy_verifications row in PENDING, links it to the user, sets tenancyStatus = PENDING, and advances currentStep from 1 to 2. Tenancy approval is asynchronous — admin review lands in Phase 6; until then a row sits in PENDING and downstream gates (POST /current-home/me/publish) return 409 STATE_CONFLICT. Preconditions:
  • The caller is authenticated.
  • currentStep is exactly 1. Submitting out of order returns 409 STATE_CONFLICT.
  • uploadId references a confirmed upload owned by the caller with fileType: 'TENANCY_DOC'.

Authentication

Bearer <accessToken> required. Scope: user.

Path parameters

None.

Query parameters

None.

Request body

Only landlordName is required. The document type and the proof upload are both optional: an applicant may name their landlord and submit nothing else. That still creates the PENDING verification and still puts the finished profile in front of a reviewer, who can approve on the rest of the profile or reject with steps: ['TENANCY'] to ask for the document. Sending an uploadId with no documentType is rejected — the reviewer would have no idea what the file is meant to be.

Example payload

Example payload — skipping the document

Response — 200 OK

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

Example response

Error responses

Example error — 409

Side effects

  • Inserts a row into the tenancy_verifications collection with status: PENDING, the supplied landlordName, landlordId, documentType, and uploadId — the last two stored as null when the applicant skipped them.
  • Updates the user document: tenancyStatus = PENDING, tenancyVerificationId = <new id>.
  • Sets users.currentStep = 2.

See also

curl