# PM System Sync

Read and write units, tenants, work orders, and ledgers in Buildium/AppFolio-class PMS (property management system — software landlords and managers use to run rentals) platforms through an org Integration row.

## When to use

- A task requires looking up unit, tenant, lease, or ledger (rent and charges record) data in the PMS.
- A task requires creating or updating a work order, tenant note, or charge in the PMS.
- A late-rent or eviction notice needs drafting from PMS ledger data for manager review.
- A maintenance request comes in and needs to be logged or escalated in the PMS.

## Tools

- `http-get`
- `http-post`
- `http-request`

## Playbook

1. Confirm which PMS instance and property portfolio the task refers to before calling any tool.
2. Look up the unit or tenant record with `http-get` (e.g. GET https://api.buildium.com/v1/rentals/units/{id}). Auth is injected by the org's Integration row for this host — never ask for, echo, or hardcode credentials.
3. To find a tenant's current ledger balance, call `http-get` against the ledger endpoint (e.g. GET https://api.buildium.com/v1/leases/{leaseId}/ledger).
4. To log a new maintenance request or work order, call `http-post` (e.g. POST https://api.buildium.com/v1/tasks) with unit, tenant, and issue description.
5. To update an existing work order's status (e.g. mark in progress or completed) or to close/cancel a record, use `http-request` with PATCH or DELETE (e.g. PATCH https://api.buildium.com/v1/tasks/{id}), since these methods are not covered by `http-post`.
6. If a maintenance request is flagged emergency (fire, flood, no heat, gas leak, security breach), stop automated processing and escalate immediately to a human via `send-message`, naming the unit, tenant, and issue.
7. If a task requires a late-rent notice or eviction notice, draft the notice text from ledger data retrieved via `http-get`, then send it to a human manager via `send-message` for review and approval — never send it directly to the tenant.
8. On a 401/403 (unauthorized/forbidden) response, or if no Integration row exists for the host, stop and message a human via `send-message` naming the service and the scopes needed.
9. Log the outcome of each PMS action taken (record updated, notice drafted, escalation sent) so the task history stays auditable.

## Failure modes

- PMS host has no Integration row configured, so every `http-get`/`http-post`/`http-request` call returns 401/403 — stop and escalate rather than retrying blindly.
- A property or unit ID from the task doesn't match any PMS record, producing a 404 — verify spelling/ID format before assuming the record doesn't exist.
- Treating a formal legal notice (late rent, eviction) as auto-sendable — these must always be routed to a human for approval, never dispatched directly.
- Missing PATCH/PUT/DELETE capability on an endpoint — if `http-request` returns 405 (method not allowed), route the update as a human handoff rather than forcing a workaround.

## Done when

- The requested PMS record (unit, tenant, work order, or ledger entry) has been read or successfully created/updated, with the resulting ID or status confirmed.
- Any legal notice has been drafted and handed to a human manager for approval, not sent autonomously.
- Any emergency maintenance issue has been escalated to a human via `send-message` immediately upon detection.