Publish listing
Current Home
Publish listing
Switch the caller’s listing to LIVE. Gated on onboarding + tenancy approval + photo + description.
POST
Publish listing
Overview
Transitions the caller’s listingstatus to LIVE. From this point the listing is visible to the matching engine and may appear as a candidate in other users’ match feeds.
The server enforces four eligibility gates before transitioning. All four must be true; any failure returns 409 STATE_CONFLICT with a detail field naming the unmet condition so the client can render targeted guidance.
users.onboardingStatus === "COMPLETE".users.tenancyStatus === "APPROVED"(set by the admin queue once the uploaded tenancy document has been reviewed — Phase 6 work).current_homes.photos.length >= 1.current_homes.description.length >= 100(the 100..150-char window enforced by step-3-description).
DRAFT or HIDDEN (re-list). Publishing an already-LIVE listing is also permitted as an idempotent no-op (the gates still run, but the setStatus write is harmless).
Authentication
Bearer <accessToken> required. Scope: user.
Path parameters
None.Query parameters
None.Request body
None.Response — 200 OK
Returns the updated Home object withstatus = LIVE.
Error responses
| Status | Code | Meaning |
|---|---|---|
| 401 | UNAUTHENTICATED | Missing, malformed, or expired access token. |
| 404 | NOT_FOUND | The user has no current_homes listing yet, or the user record itself was not found. |
| 409 | STATE_CONFLICT | One of the four eligibility gates failed. detail identifies which gate (Onboarding must be complete to publish, Tenancy verification must be APPROVED to publish, Add at least one photo before publishing, or Add a description (100..150 chars) before publishing). |
Example error — 409 (tenancy not approved)
Example error — 409 (no photos)
Side effects
- Sets
current_homes.status = "LIVE"on the caller’s listing. updatedAtis bumped.- Enqueues a
match.recomputejob for the owner so the matcher picks up the newly-eligible listing (Phase 3 worker; stub in Phase 2). - Does NOT touch
users.onboardingStatusorusers.tenancyStatus— they are inputs, not outputs of this endpoint.
See also
- Hide listing — the inverse transition.
- Get my current home
- Add listing photos — required before publish if the listing has none.
- Step 1 — tenancy — uploads the document that the admin queue reviews.
- Onboarding state machine