中文版

Landlord API — Enquiries & Offers (v1)

A landlord's AI agent can read and reply to viewing requests, and read offers, through the Landlord Rental API v1 with the existing Enquiries & offers permission. The agent never sees tenant contact details and never takes a legally binding action; offers stay read-only in the portal.

  • Predecessor Landlord API slices 1–3 (foundation, idempotent sync, media sync)
  • ADRs 0056 · 0063
  • Status Approved

View source markdown ↗ generated by claude-opus-5-5 · diagrams mermaid

Summary

A landlord's AI agent can read and reply to viewing requests, and read offers, through the Landlord Rental API v1 with the existing Enquiries & offers permission. The agent never receives tenant contact details and never takes a legally binding action: offers stay read-only and are handled in the portal.

  • Status Draft · 2026-10-03
  • Builds on Landlord API slices 1–3 (foundation, idempotent sync, media sync)
  • Scope enquiries:read, enquiries:write
  • Surface 9 new v1 operations under /api/v1/rental
  • Areas backend/go, rental portal, rental marketplace docs
  • Related ADRs 0056, 0063

Goal

Success means an agent can answer "what needs my attention?", reply to a tenant in the thread, and confirm, counter, or decline a viewing time, without ever receiving tenant contact details and without taking any legally binding action.

Decisions

D1 · What the agent can do

read + reply
  • Read viewing requests, threads and offers.
  • Send thread messages.
  • Confirm, counter, or decline viewing times.
  • Offers are read-only: accept, counter, decline stay in the portal.

D2 · Tenant personal data

first name only
  • Always first name only.
  • Never full name, phone, email, NRIC, user ids, or the exact address_line.

D3 · Test keys

listing mode
  • A viewing request takes the test/live mode of its listing.
  • Wrong mode reads as 404. No new is_test columns.

D4 · Disclosure to tenants

sent_via = api
  • Messages and system messages caused by an API key are marked.
  • Tenant sees "Sent via {landlord first name}'s assistant"; landlord sees "Sent via your assistant".

D6 · Scope vocabulary

no Bun change
  • Reuse enquiries:read / enquiries:write.

D7 · D8 · Reads and retries

safe
  • v1 reads never set read_at.
  • Idempotency-Key on the message post only.

D5 · How is the v1 layer built?

Dedicated v1 handlers in v1_enquiry_handler.go calling the existing use cases, with their own response DTOs and error mapping.

The v1 contract differs enough (first-name-only rule, test/live isolation, pagination, frozen error envelope) that a separate adapter stays simple, and portal handlers stay untouched so the portal cannot regress.

Rejected: sharing portal handlers with v1 branches (highest regression risk, handlers do not use the error renderer); new v1-specific use-case methods (puts adapter policy into the shared capability layer and duplicates state rules).

Endpoints

All routes are mounted under /api/v1/rental through the existing v1 pipeline.

#Method and pathScopePurpose
1GET /viewing-requestsenquiries:readLandlord's viewing requests, most recent activity first. Filters status, listing_id. Paginated.
2GET /viewing-requests/{id}enquiries:readOne request.
3POST /viewing-requests/{id}/confirmenquiries:write{ "confirmed_time" }, one of proposed_times. From pending.
4POST /viewing-requests/{id}/counterenquiries:write{ "proposed_times" }, 1–3 future RFC 3339 times. From pending.
5POST /viewing-requests/{id}/declineenquiries:write{ "reason" }, required. From pending or countered.
6GET /viewing-requests/{id}/messagesenquiries:readThread, oldest first, paginated. Does not mark messages read.
7POST /viewing-requests/{id}/messagesenquiries:write{ "body" }, 1–2,000 characters. Only while writable. Supports Idempotency-Key.
8GET /offersenquiries:readLandlord's offers. Filters status, viewing_request_id. Paginated.
9GET /offers/{id}enquiries:readOne offer.

Viewing request

{
  "id": "…",
  "listing_id": "…",
  "property_id": "…",
  "status": "pending | countered | confirmed | completed | declined | withdrawn | cancelled",
  "proposed_times": ["2026-10-10T10:00:00+08:00"],
  "confirmed_time": null,
  "decline_reason": null,
  "tenant": { "first_name": "Aisha" },
  "listing": { "building_name": "Arcoris", "area": "Mont Kiara", "monthly_rent": 2800 },
  "unread_count": 2,
  "last_message_at": "…",
  "created_at": "…",
  "updated_at": "…"
}

Message

{
  "id": "…",
  "viewing_request_id": "…",
  "sender": "landlord | tenant",
  "sent_via": "api | null",
  "body": "…",
  "created_at": "…",
  "read_at": null
}

sender is a role, never a user id.

Offer

Identity
id, viewing_request_id, listing_id
Status
pending | countered | accepted | declined | withdrawn, plus decline_reason and last_actor (landlord | tenant)
Terms
monthly_rent, start_date, term_months, security_deposit_months, utility_deposit_months, advance_rent_months, special_conditions
Timestamps
created_at, updated_at
Never
User ids

Pagination

Same {items, pagination} envelope and page/limit rules as GET /properties: limit default 20, max 100, out-of-range falls back to 20.

Behaviour

Access

  1. API key auth
  2. Per-key rate limit
  3. Audit context
  4. Landlord role
  5. RequireKeyScope("enquiries", "read" | "write"); missing scope returns 403 insufficient_permission.

Ownership and mode isolation

A request is visible only when owner_user_id equals the key's user and the listing's is_test equals the key's mode. Anything else returns 404. Offers resolve through their viewing request's listing. List queries apply both conditions in SQL so pagination counts are correct.

Every lookup and list query filters on owner and listing mode
Every lookup and list query filters on owner and listing mode.

Tenant data

The v1 DTO fills tenant.first_name from the same source the portal uses before confirmation, regardless of status. The contact-reveal fields of RequestDetail (full name, phone, address_line) are never copied into v1 DTOs.

Actions

Each action calls the existing use case unchanged, so rules match the portal. The tenant receives the same notifications as when the landlord acts in the portal.

  • confirm from pending; time in proposed_times; same time again is idempotent; landlord phone on file 200
  • counter from pending; 1–3 future times; appends the existing system message 200
  • decline from pending or countered; reason required; existing decline email to tenant 200
  • message IsThreadWritable: open requests, completed in offer/agreement stage, or ≤ 30 days after tenancy end; runs chat judge + admin alerts 201
Viewing request states; transitions marked (API) are available to the agent
Viewing request states; transitions marked (API) are available to the agent.

"Sent via assistant" label

  • New nullable column sent_via TEXT on rental_messages ('api' or NULL).
  • Set to 'api' when actor_type = api_key in the request context, for landlord-typed messages and for system messages produced by API-triggered counter and decline.
  • Tenant thread renders "Sent via {landlord first name}'s assistant"; landlord thread renders "Sent via your assistant". Strings in en, ms, zh.
  • Existing rows stay NULL.

No read side effects

GET /viewing-requests/{id}/messages uses a read path that does not update read_at. Portal unread counts are unaffected by agent reads.

Errors

All endpoints use the frozen v1 envelope { "error": { "code", "message", "fields?" }, "request_id" }. The v1 handler maps use-case errors to codes; internal error text never reaches the caller.

Reused codes: validation_failed, all 401/403/429 codes, internal_error, auth_unavailable, rate_limit_unavailable, route_not_found, method_not_allowed, idempotency_conflict.

StatusNew codeWhen
404viewing_request_not_foundNot found, not this landlord's, or wrong mode.
404offer_not_foundSame rules for offers.
400landlord_phone_requiredConfirm while the landlord has no phone on file.
409viewing_request_status_conflictAction not allowed in the current status.
409thread_closedMessage sent to a thread that is no longer writable.

validation_failed (with fields) covers: confirmed_time not in proposed_times or in the past; proposed_times empty, more than 3, or past; missing decline reason; empty or over-long message body; unknown status filter.

Frontend and documentation

Key form
Enable Enquiries & offers (unchecked by default), remove "no endpoint yet". "Money, agreements, tenants" stays disabled. frontend/solidstart/apps/rental
Thread views
Render the sent_via label in tenant and landlord threads; i18n en/ms/zh.
Dashboard API card
Mention replying to viewing requests.
API guide
frontend/astro/apps/rental/src/docs/landlord-api-v1.md: new "Enquiries and offers" section (permissions, first-name-only rule, statuses and allowed actions, "reply to a viewing request" workflow, new error codes). New agent rule: confirm with the landlord before declining a viewing; offers are handled in the portal.

Contract and testing

backend/go/openapi/rental-v1.yaml gains 9 operations, schemas, 5 new error codes, and Idempotency-Key on the message post. The drift test and contract table enforce agreement.

Go tests

  • Contract-table rows for all 9 routes (method, path, scope, status, body keys).
  • Golden no-PII test: no v1 viewing-request, message, or offer body contains phone, email, full_name, nric, tenant_user_id, or address_line, including for a confirmed request.
  • Isolation: another landlord's request and a wrong-mode request return 404 and are absent from lists and counts.
  • Read without side effects: read_at stays NULL after a v1 read.
  • Actions: confirm, counter, decline from allowed statuses succeed and otherwise return 409 viewing_request_status_conflict; landlord_phone_required; thread_closed.
  • Label: a key-posted message stores sent_via = 'api', a portal-posted one stores NULL.
  • Idempotent message post: replay returns Idempotent-Replay: true and creates no second row.

Frontend tests

  • Label render in tenant and landlord threads.
  • Key-form bundle test updated (Enquiries & offers enabled, unchecked).

Migration

One nullable column, rental_messages.sent_via. No backfill; nothing is in production.

Risks