The data model at a glance
Entities
Organization
The unit an API key is scoped to — the customer-of-Monterey entity. Clients with multi-org keys see results grouped byorganization_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 carriesorganization_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 isfrequency_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-shapedid (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.
organization_id conventions documented in 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. Charges that autopay schedules produce show up as Transactions like any other payment, so your existing sync and reconciliation flows pick them up automatically.