Onboarding step 1 — tenancy
Onboarding
Onboarding step 1 — tenancy
Submit tenancy verification details. Step 1 of 4.
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 confirmedTENANCY_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.
currentStepis exactly1. Submitting out of order returns409 STATE_CONFLICT.uploadIdreferences a confirmed upload owned by the caller withfileType: 'TENANCY_DOC'.
Authentication
Bearer <accessToken> required. Scope: user.
Path parameters
None.Query parameters
None.Request body
| Field | Type | Required | Allowed values / Constraints | Example |
|---|---|---|---|---|
landlordId | string | null | no | 24-char MongoDB ObjectId. Pass when the user selected an entry from /onboarding/landlords; otherwise omit or send null. When set, it must reference an active landlord or the request is rejected with 400 VALIDATION_FAILED. | null |
landlordName | string | yes | 1..200 chars. Used as the free-text fallback when landlordId is null. When landlordId IS set, the server overwrites this with the landlord’s canonical name, so any client value is ignored. | Camden Council Housing |
documentType | enum | yes | TENANCY_AGREEMENT, RENT_STATEMENT, LANDLORD_LETTER | TENANCY_AGREEMENT |
uploadId | string | yes | 24-char ObjectId of a previously confirmed upload with fileType: 'TENANCY_DOC', owned by the caller. | 66400a8f1c2b4d5e6f7a8b90 |
Example payload
Response — 200 OK
Returns the refreshed onboarding state (same shape asGET /onboarding/state).
| Field | Type | Allowed values | Example |
|---|---|---|---|
onboardingStatus | enum | IN_PROGRESS, COMPLETE | IN_PROGRESS |
currentStep | integer | null | advances to 2 | 2 |
tenancyStatus | enum | becomes PENDING | PENDING |
Example response
Error responses
| Status | Code | Meaning |
|---|---|---|
| 400 | VALIDATION_FAILED | Body fails Zod validation (bad ObjectId shape, unknown documentType, etc.) or uploadId does not reference a TENANCY_DOC. |
| 401 | UNAUTHENTICATED | Missing, malformed, or expired access token. |
| 404 | NOT_FOUND | uploadId does not belong to the caller (or does not exist). |
| 409 | STATE_CONFLICT | currentStep is not 1, or onboarding is already complete. |
Example error — 409
Side effects
- Inserts a row into the
tenancy_verificationscollection withstatus: PENDING, the suppliedlandlordName,landlordId,documentType, anduploadId. - Updates the user document:
tenancyStatus = PENDING,tenancyVerificationId = <new id>. - Sets
users.currentStep = 2.
See also
- Onboarding state machine
- Upload flow — how to obtain the
uploadId. - Presign upload URLs
- Confirm uploads
- Step 2 — current home