> ## Documentation Index
> Fetch the complete documentation index at: https://docs.paypathiq.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Property-management integration planning

> Plan service-charge arrears mappings and understand the current API boundary.

<Warning>
  This is a planning example, not a runnable property-management API integration. The current API accepts only `credit_union.v1` and requires credit-union loan fields. There is no property-management profile, property/unit resource or invoice resource in this contract. Do not represent service charges or rent as loans to make a request pass validation.
</Warning>

## Example: service-charge arrears

An owners' management company authorizes collection of EUR 1,250 in service-charge arrears from a liable owner. The managing agent supplies records from its property-management system. EUR 250 is subsequently received in that source system, leaving EUR 1,000 authorized for collection.

These are proposed domain mappings to agree during integration design, not additional request fields:

| Property-management concept | Mapping to discuss |
| - | - |
| Creditor, such as the owners' management company | Client; confirm the creditor rather than assuming the managing agent fills this role |
| Managing agent's source connection | Integration with access to the agreed Client and Portfolio |
| Liable owner, person or business | Customer; confirm liability and any joint parties |
| Contact person or representative | Contact, separate from liability |
| Amount authorized for collection | Receivable; agree whether a placement represents one charge or an aggregate of charges |
| Service-charge period, invoice, property or unit | Requires an agreed property-management contract; no dedicated fields exist today |
| Money received outside PayPathIQ | Payment observation concept; agree allocation across charges and placements |

Keep creditor identity, liability, contact details and collection authority separate. A property address does not by itself establish a liable Customer or permission to contact someone.

## Before runnable examples

Agree the property-management profile and implement its validation, grants, runtime handling and OpenAPI together. Decisions include:

* Supported debt types: service charges, rent or other charges, and required source facts for each.
* Stable opaque IDs for parties and placements, plus property/unit and invoice references and their privacy treatment.
* Charge aggregation, due dates, credits, adjustments and payment allocation; the existing API supports only full refunds and reversals of a Payment observation.
* The information partners need back: current collection progress, communications or reporting would need capabilities beyond the existing source-representation reads.

Once those decisions are implemented, publish runnable examples that validate against that profile. The [credit-union walkthrough](/credit-union) shows today's implemented flow and its reconciliation rules.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.