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

# Domain concepts

> How organizations, persons, accounts, transactions, payment methods, and autopay schedules fit together — and the identifiers that bridge them to your systems.

Monterey services loan accounts across multiple Loan Management Systems (LMSes). The Reporting API exposes a single normalized data model that's identical regardless of which LMS sits behind any given account — that's why a multi-LMS portfolio shows up here as one consistent surface. Four core entities — Organizations, Persons, Accounts, Transactions — plus per-account lifecycle history and two payment-operations entities: Payment methods and Autopay schedules. Everything an API key can see is anchored to an Organization.

## The data model at a glance

```mermaid theme={null}
erDiagram
    ORGANIZATION ||--o{ ACCOUNT : "owns / services"
    PERSON ||--o{ ACCOUNT : "is borrower on"
    PERSON ||--o{ PAYMENT_METHOD : "stores"
    ACCOUNT ||--o{ TRANSACTION : "has"
    ACCOUNT ||--o{ LIFECYCLE_EVENT : "has"
    ACCOUNT ||--o{ AUTOPAY_SCHEDULE : "has"
    PAYMENT_METHOD ||--o{ AUTOPAY_SCHEDULE : "funds"

    ORGANIZATION {
        string id "ULID, 01K..."
        string display_name
        string legal_name
    }

    PERSON {
        string id "ULID, 01J..."
        string display_name
    }

    ACCOUNT {
        string id "ULID, 01J..."
        string organization_id
        string primary_borrower_party_id
        string external_contract_number
        int current_balance_cents
        string status_code
    }

    TRANSACTION {
        string transaction_id "ULID"
        string account_id
        string organization_id
        string type "payment | adjustment | ..."
        int amount_cents
        date effective_at
    }

    PAYMENT_METHOD {
        string id "ULID"
        string party_id
        string instrument_type "card | bank_account | wallet"
        string last_four
        bool is_active
    }

    AUTOPAY_SCHEDULE {
        string id "ULID"
        string account_id
        string payment_method_id
        int amount_cents
        string frequency_unit "day | week | month | year"
        date next_run_date
        string status "active | paused | cancelled | expired"
    }
```

## Entities

### Organization

The unit an API key is scoped to — the customer-of-Monterey entity. Clients with multi-org keys see results grouped by `organization_id`; the field appears on every account, transaction, and report row so you can fan out by organization without an extra lookup.

### Person

An individual party — typically a borrower on one or more accounts. A Person can be the primary borrower on many Accounts; `GET /persons/{party_id}/accounts` returns that list.

### Account

A loan or credit account — the central entity. Has one Organization (`organization_id`), one primary borrower Person (`primary_borrower_party_id`), and many Transactions and Lifecycle events. The list response (`AccountRow`) is intentionally narrow; for richer per-account data including borrower and contract details, use `GET /accounts/{id}` which returns `AccountDetailRow`.

### Transaction

Money movement on an Account — payments, adjustments, fees. Every transaction carries `organization_id` so multi-org keys can group results without joining back to the account. Transactional reports (Cash Receipts, NSF Returns, etc.) are pre-shaped queries over the same underlying Transaction table.

### Lifecycle event

A status change on an Account — opened, charged off, paid in full, etc. Useful for reconstructing the account's history or auditing why a given report row appears (or doesn't).

### Payment method

A stored payment instrument — card, bank account, or wallet — belonging to a Person (`party_id`). The API returns only display-safe metadata (`last_four`, `card_brand`, expiry, bank name), never full card or account numbers, and the instrument data is immutable: to change a card, create a new payment method and deactivate the old one. Removed methods drop out of the per-account list (`GET /accounts/{id}/payment-methods`) but stay visible with `is_active: false` in the top-level `/payment-methods` list, so historical payments remain auditable.

### Autopay schedule

A recurring payment plan on an Account, funded by one Payment method. The cadence is `frequency_interval` × `frequency_unit` (every two weeks is `2` + `week`), starting at `start_date`; `next_run_date` tells you when the next charge lands. Month and year cadences can pin runs to a day of the month with `anchor_day`. A schedule moves through `active`, `paused`, `cancelled`, and `expired` states — pausing is reversible via `PATCH`, cancelling is not.

## Identifier conventions

You'll see three classes of identifier on accounts. Use the right one for the right purpose.

**Monterey IDs** — every entity carries a ULID-shaped `id` (e.g. `01J...`, `01K...`) that Monterey assigns and owns. Use these for path lookups (`/accounts/{account_id}/transactions`) and as foreign keys in your own database when you store Monterey records.

**`external_contract_number`** — the contract identifier *you* (or your LMS on your behalf) pass to Monterey at account-creation time. This is the bridge back to your own systems: when you need to join Monterey data with records in your platform, `external_contract_number` is what most clients key on. Monterey doesn't generate it — you do — which is why it's stable across any MFS-side changes.

**`external_account_number`** — the account number assigned by the source LMS that Monterey services on your behalf. Stable for the lifetime of the account; useful if you're also pulling raw exports from the LMS side and need to cross-reference. Not generally the right field for joining to your own systems — use `external_contract_number` for that.

**`primary_borrower_party_id`** — the ID of the Person who's the primary borrower on the account. (Field name says "party" because that's Monterey's umbrella term for any actor — person or organization. For accounts, it's always a Person.)

## Reports vs resource endpoints

There are two ways to query the same underlying data:

**Reports** answer pre-shaped business questions. "All NSF returns in March" is one HTTP GET. The Reporting API ships ten report endpoints today — Cash Receipts, NSF Returns, Cash and Non-Cash Adjustments, Monthly Payment Register, New Sales, Write-Off, Paid In Full, Aged Balance, Delinquency.

**Resource endpoints** let you compose your own queries. Walk from an Organization to its Accounts to a specific Account's Transactions; pull all Transactions across the orgs your key can see; drill into a single Person and find every Account they're a borrower on.

**When to use which:**

* Pre-shaped business question → use a Report.
* Composable / drill-down / "this slice of this account" → use a resource endpoint.
* One-off ad-hoc query → either works; reports are usually less code.

Both surfaces share the same Bearer auth, pagination, date-range, and `organization_id` conventions documented in [Conventions](/api-reference/conventions). The difference is shape: reports return rows ready to feed into a spreadsheet or BI tool; resource endpoints return entity objects you compose into your own graph.

**Payment operations** are the third surface — the only one that writes. Payment method and autopay endpoints follow the resource-endpoint conventions (same auth, same pagination on lists, 404 for out-of-scope IDs) and add `POST`/`PATCH`/`DELETE` semantics documented in [Conventions](/api-reference/conventions). Charges that autopay schedules produce show up as Transactions like any other payment, so your existing sync and reconciliation flows pick them up automatically.