POST
Publish listing

Overview

Transitions the caller’s listing status 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.
  1. users.onboardingStatus === "COMPLETE".
  2. users.tenancyStatus === "APPROVED" (set by the admin queue once the uploaded tenancy document has been reviewed — Phase 6 work).
  3. current_homes.photos.length >= 1.
  4. current_homes.description.length >= 50 (the 50..150-char window enforced by step-3-description).
The transition is allowed from 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 with status = LIVE.

Error responses

Example error — 409 (tenancy not approved)

Example error — 409 (no photos)

Side effects

  • Sets current_homes.status = "LIVE" on the caller’s listing.
  • updatedAt is bumped.
  • Enqueues a match.recompute job for the owner so the matcher picks up the newly-eligible listing (Phase 3 worker; stub in Phase 2).
  • Does NOT touch users.onboardingStatus or users.tenancyStatus — they are inputs, not outputs of this endpoint.

See also

curl