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).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.