Partner API — Enquiries and Offers
Authorised partners can read and respond to tenant viewing requests, exchange thread messages, and read offers through the Partner API, limited to properties they created. Consent-only permissions, scoped SQL readers, existing landlord workflows, and audit attribution preserve privacy and access boundaries without granting offer negotiation or acceptance authority.
- Predecessor Partner API foundation (P1), property lifecycle (P2), and P3 shared landlord scope and consent presentation
- Status Approved
Let authorised partners handle tenant enquiries between listing management and tenancy operations: read viewing requests, respond to viewing times, exchange thread messages, and read offers. Access is limited to properties created by the calling partner; offer negotiation and acceptance remain outside the API.
Decisions at a glance
| Decision | Locked-in choice |
|---|---|
| Operation scope | Mirror landlord v1 exactly: viewing reads/actions, thread reads/posts, offer reads only. |
| Property visibility | The immutable origin_partner_id must equal the caller. No all-properties opt-in. |
| Consent | Both enquiries:read and enquiries:write require landlord approval. |
| Implementation | Reuse V1EnquiryHandler and existing workflows; pass explicit port.LandlordScope and filter in SQL. |
| Identity | Act as the landlord; keep sent_via: "api" and record the real partner in audit. |
| Retries | Reuse message-post idempotency with landlord-scoped partner keys. No new viewing-action idempotency contract. |
| Lifecycle | Archived history remains readable. Existing rental workflow rules govern actions and messages. |
Intent and success
Partners start with first-party white-label channels and later include external portals and CRMs. They need to serve authorised landlords through the gap between listing management and P3 tenancy operations, without authority to negotiate or accept offers.
Success means viewing-request list/detail, confirm/counter/decline, thread read/send, and offer list/detail on the partner surface. Tenant disclosure and business behaviour match the existing landlord v1 API.
- Programme
- The enquiries-and-offers item explicitly deferred by P1; no change to P1–P3 acceptance criteria.
- Dependencies
- P1 Partner API foundation, P2 property lifecycle, and P3 shared landlord scope and consent presentation.
- Ownership
backend/go,backend/bun,frontend/solidstart/apps/rental, andfrontend/solidstart/apps/panel.- Concurrent work
- The source records P2 frontend and P3 backend/frontend implementation in other sessions. Integrate with their delivered interfaces; do not duplicate that work.
Architecture and alternatives
Shared handlers, explicit readers
Reuse V1EnquiryHandler and migrate enquiry readers to P3’s port.LandlordScope.
One enquiry workflow preserves v1 response shaping and business behaviour. SQL visibility keeps detail access, page contents, and totals consistent with P3.
Separate partner handlers/readers reduce changes to v1 callers but duplicate shaping and visibility logic. Per-resource checks around unchanged readers split authorisation between checks and queries and still need SQL changes for pagination.
Existing foundation, not implementation claims
Observed code boundaries and source designs
adapter/inbound/http/v1_routes.gomounts the nine enquiry routes usingenquiries:read/enquiries:write; deeper offer-action paths deliberately return404before authentication.adapter/inbound/http/v1_enquiry_handler.goshapes viewing requests, messages, and offers without user IDs or structured tenant contact details. The action helper reads the visible request before the workflow and again afterwards.- Message posting checks visibility before sending; replay resolves through
GetOwnerMessage.PeekMessagesreads never mark messages read. ViewingRequestUseCase:ListOwnerPage,GetOwnerView,PeekMessages,GetOwnerMessage.OfferUseCase:ListLandlordPage,GetLandlordView. These currently take(ownerID/landlordID, isTest), not a partner-aware scope.adapter/outbound/persistence/postgresql/message_repository.gocurrently stampssent_via = 'api'only foractor_type == 'api_key'.- P1 combines key ceiling, landlord grant, and live landlord scope;
partner_scope.gocontains the landlord-scoped idempotency-key helper. - P3 introduces
port.LandlordScope{UserID, IsTest, PartnerID}, consent-only enforcement, shared translated scope presentation, and a consent-only panel group. Reuse those delivered seams.
Source designs in docs/superpowers/specs/: 2026-10-03-partner-api-p1-design.md, 2026-10-03-landlord-api-enquiries-design.md, and 2026-10-07-partner-api-p3-design.md.
API contract
Base: /api/partner/v1/landlords/:landlord_id. The following relative paths preserve landlord v1 bodies and responses.
| Method | Relative path | Required scope |
|---|---|---|
GET | /viewing-requests | enquiries:read |
GET | /viewing-requests/:id | enquiries:read |
POST | /viewing-requests/:id/confirm | enquiries:write |
POST | /viewing-requests/:id/counter | enquiries:write |
POST | /viewing-requests/:id/decline | enquiries:write |
GET | /viewing-requests/:id/messages | enquiries:read |
POST | /viewing-requests/:id/messages | enquiries:write |
GET | /offers | enquiries:read |
GET | /offers/:id | enquiries:read |
- Viewing list filters
status,listing_id.- Offer list filters
status,viewing_request_id.- Write body fields
- Confirm:
confirmed_time; counter:proposed_times; decline:reason; message:body. - Preserved contract
- Existing body validation, response fields, timestamps, sorting, and pagination envelope.
Authorisation and reader boundaries
Three visibility predicates
- Landlord match
Resolve the existing listing/property relationship; the landlord or owner must match
scope.UserID. - Mode match
The existing property/listing mode rule must match
scope.IsTest. Partner requests are live-only. - Origin match
When
scope.PartnerIDis present, the property’sorigin_partner_idmust match it. Rental-app properties and properties from another partner are invisible.
Use P3’s explicit port.LandlordScope and existing handler scope-construction convention. Do not hide repository authorisation in context values or introduce a second scope type. Landlord v1 has no partner ID and keeps its existing live/test visibility.
Thread and write gates
PeekMessagesandGetOwnerMessageresolve the parent through the scoped reader before reading messages; replay retains the message-to-thread membership check.- The action helper resolves with the full scope before confirm/counter/decline and uses the same scope for its refreshed response. Message posting performs the same scoped check before sending.
- Existing use cases enforce ownership, valid transitions, thread writability, message validation, and lifecycle rules.
- Origin is immutable: no new property-origin mutation or locking policy, and no new enquiry archive policy.
- Migrate every affected caller and test double to the explicit scope. No legacy-signature aliases or compatibility wrappers; portal workflows otherwise remain unchanged.
Scopes, consent, and administration
Add exactly enquiries:read and enquiries:write to grant vocabulary and the consent-only set. Do not create separate offers or messages scopes.
- Admin sets the ceiling
Extend Bun’s partner-key permission map and the panel form with both names, in P3’s consent-only group. A key ceiling is not landlord consent; existing keys/grants are not automatically widened.
- Landlord claims and approves
A partner-created landlord must claim the account and approve a connect request. Requests accept these scopes within the key ceiling; approval is the only grant path.
- Approval replaces the scope set
Re-approval replaces, not merges, scopes. Include previous permissions in the request if they must be retained. Existing revocation and key/partner disablement enforcement remains in force.
Landlord-facing labels
| Scope | English label | Meaning |
|---|---|---|
enquiries:read | Read enquiries and offers | View viewing requests, their conversations, and offers. |
enquiries:write | Respond to enquiries | Confirm, propose alternative times, or decline viewing requests, and send messages. |
Extend P3’s shared labels in English, Malay, and Chinese. Consent and Connected apps use the same tenant-records group and explain enquiries and tenancy records on properties created by the partner. Preserve the visible raw-name fallback for unknown future scopes. No new partner dashboard or tenant UI.
Messages, attribution, and idempotency
Identity and channel
- Sender
- The landlord remains
SenderUserID. - API channel
- Extend stamping to partner actors for ordinary messages and action-generated system messages:
sent_via: "api". Normal session messages keep existing behaviour. - Tenant disclosure
- Keep existing tenant/landlord assistant disclosure driven by the API marker. No partner-specific branding or sender role.
- Audit
- Record the actual partner through the existing partner audit mechanism. Keep the partner actor in context; do not convert it to
api_keyjust to obtain stamping. - Read side effects
- Message GETs and single-message replay lookup never mark messages read.
Message-post retries
Reuse the existing executor and scopedIdempotencyKey so one partner key can reuse a client key across landlords without collision. Preserve method, path, raw-body fingerprinting, and resource-type semantics.
| Case | Response |
|---|---|
| First successful post | 201. |
| Matching replay | Original message, 200, Idempotent-Replay: true. |
| Conflicting key reuse | Existing 409 response. |
| No idempotency header | Existing ordinary message-post behaviour. |
Viewing actions keep existing v1 retry behaviour, including unchanged confirmation of an already-confirmed identical time. Add no new idempotency-header requirement or background retry system.
Errors and lifecycle
- Hidden viewing request or thread
404 viewing_request_not_found.- Hidden offer
404 offer_not_found.- Error source
- Existing codes in
adapter/inbound/http/enquiry_error_mapper.go; reuse v1 enquiry rendering and partner auth/grant errors. - Validation and transitions
- Existing status codes and error bodies remain unchanged. No new not-found codes.
- History and writes
- Archived history remains readable; writes follow existing rental workflow rules, not a blanket archive restriction.
Verification and acceptance
- SQL list/detail isolation across landlords, partners, and test/live mode, including properties without partner origin.
- Pagination and totals include only visible matches even when hidden rows would otherwise fill the page; existing filters remain correct.
- Key ceiling and active grant are both required. Landlord creation cannot provision consent-only scopes; approved connect requests can.
- Viewing actions/messages work on authorised own-property requests and cannot affect foreign-property requests.
- Ordinary and action-generated messages carry
sent_via: "api"; session behaviour stays unchanged and partner audit attribution is retained. - Reads do not mark messages read. Replays return the original without duplication; conflicts fail; landlord-scoped keys are isolated; revoked or inaccessible replay cannot leak content.
- Offer reads work while offer actions remain unlisted. Landlord v1 live/test contracts remain unchanged.
Runtime and browser proof
Use the permitted test environment and isolated fixtures. Exercise a real approved grant through viewing list/detail, a viewing action, message post/replay, offer list/detail, and an inaccessible-property attempt.
Browser verification covers consent labels and panel scope selection under frontend browser rules. Verify all three locale mappings and representative rendered translations without tests that merely pin wording.
Contract documentation
Update the separate Partner OpenAPI and existing API documentation with routes, required scopes, property visibility, consent-only grants, attribution, and retries. Do not change landlord v1’s public contract.
Non-goals and delivery boundary
- Offer creation/counter/accept/decline/withdrawal; tenant-side viewing operations; cancelling confirmed viewings.
- Marking messages read; a separate inbox API; all-properties grants; new contact disclosure; partner-branded tenant UI.
- Webhooks, sandbox mode, self-service signup, developer portal, and unrelated refactoring.