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.
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.
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 newis_testcolumns.
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-Keyon 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 path | Scope | Purpose |
|---|---|---|---|
| 1 | GET /viewing-requests | enquiries:read | Landlord's viewing requests, most recent activity first. Filters status, listing_id. Paginated. |
| 2 | GET /viewing-requests/{id} | enquiries:read | One request. |
| 3 | POST /viewing-requests/{id}/confirm | enquiries:write | { "confirmed_time" }, one of proposed_times. From pending. |
| 4 | POST /viewing-requests/{id}/counter | enquiries:write | { "proposed_times" }, 1–3 future RFC 3339 times. From pending. |
| 5 | POST /viewing-requests/{id}/decline | enquiries:write | { "reason" }, required. From pending or countered. |
| 6 | GET /viewing-requests/{id}/messages | enquiries:read | Thread, oldest first, paginated. Does not mark messages read. |
| 7 | POST /viewing-requests/{id}/messages | enquiries:write | { "body" }, 1–2,000 characters. Only while writable. Supports Idempotency-Key. |
| 8 | GET /offers | enquiries:read | Landlord's offers. Filters status, viewing_request_id. Paginated. |
| 9 | GET /offers/{id} | enquiries:read | One 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, plusdecline_reasonandlast_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
- API key auth
- Per-key rate limit
- Audit context
- Landlord role
RequireKeyScope("enquiries", "read" | "write"); missing scope returns403 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.
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.
-
confirmfrompending; time inproposed_times; same time again is idempotent; landlord phone on file 200 -
counterfrompending; 1–3 future times; appends the existing system message 200 -
declinefrompendingorcountered; reason required; existing decline email to tenant 200 -
messageIsThreadWritable: open requests, completed in offer/agreement stage, or ≤ 30 days after tenancy end; runs chat judge + admin alerts 201
"Sent via assistant" label
- New nullable column
sent_via TEXTonrental_messages('api'orNULL). - Set to
'api'whenactor_type = api_keyin 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.
| Status | New code | When |
|---|---|---|
| 404 | viewing_request_not_found | Not found, not this landlord's, or wrong mode. |
| 404 | offer_not_found | Same rules for offers. |
| 400 | landlord_phone_required | Confirm while the landlord has no phone on file. |
| 409 | viewing_request_status_conflict | Action not allowed in the current status. |
| 409 | thread_closed | Message 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_vialabel 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, oraddress_line, including for a confirmed request. - Isolation: another landlord's request and a wrong-mode request return
404and are absent from lists and counts. - Read without side effects:
read_atstaysNULLafter 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 storesNULL. - Idempotent message post: replay returns
Idempotent-Replay: trueand 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.