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

# Integration patterns

> Practical recipes for transaction sync, borrower-aware account ingestion, person enrichment, and autopay setup.

These examples assume you have exchanged your API key for an access token as described in [Authentication](https://docs.montereyfinancial.com/api-reference/authentication.md). Store the token in memory and replace it before its 3600-second expiry.

The base URL is `https://api.montereyfinancial.app`, and every endpoint begins with `/v1`.

## Daily transaction sync

Pull a bounded date window, follow `next_cursor`, and deduplicate on `transaction_id` in your database.

```python theme={null}
import os
import random
import time
from datetime import date, timedelta

import httpx

base_url = "https://api.montereyfinancial.app"
headers = {"Authorization": f"Bearer {os.environ['MFS_ACCESS_TOKEN']}"}

def fetch_transactions(day: date) -> list[dict]:
    items: list[dict] = []
    cursor: str | None = None
    while True:
        params = {
            "from": day.isoformat(),
            "to": day.isoformat(),
            "limit": 500,
        }
        if cursor:
            params["cursor"] = cursor
        response = httpx.get(
            f"{base_url}/v1/transactions",
            params=params,
            headers=headers,
            timeout=30.0,
        )
        if response.status_code == 429:
            retry_after = float(response.headers["Retry-After"])
            time.sleep(retry_after + random.uniform(0, 1))
            continue
        response.raise_for_status()
        page = response.json()
        items.extend(page["items"])
        cursor = page["page"]["next_cursor"]
        if not cursor:
            return items

yesterday = date.today() - timedelta(days=1)
for transaction in fetch_transactions(yesterday):
    save_to_warehouse(transaction)  # Upsert by transaction_id.
```

Re-running a date window is safe when your write is idempotent.

## Ingest accounts and borrower roles

Account responses contain one role-carrying `borrowers` list. Do not depend on a closed role enum.

```typescript theme={null}
type Borrower = {
  party_id: string;
  display_name: string;
  role: string; // Open set: preserve unknown values.
  is_primary: boolean;
};

type Account = {
  id: string;
  organization_id: string;
  external_id: string | null;
  external_contract_id: string | null;
  borrowers: Borrower[];
};

type PageMeta = { next_cursor: string | null; has_more: boolean; limit: number };
type AccountsPage = { items: Account[]; page: PageMeta };

let cursor: string | null = null;
do {
  const url = new URL("https://api.montereyfinancial.app/v1/accounts");
  url.searchParams.set("limit", "500");
  if (cursor) url.searchParams.set("cursor", cursor);

  const response = await fetch(url, {
    headers: { Authorization: `Bearer ${process.env.MFS_ACCESS_TOKEN}` },
  });
  if (!response.ok) throw new Error(await response.text());

  const page = (await response.json()) as AccountsPage;
  for (const account of page.items) {
    const primary = account.borrowers.find((borrower) => borrower.is_primary);
    upsertAccount(account, primary);
  }
  cursor = page.page.next_cursor;
} while (cursor);
```

Always persist the required Monterey `id` as your durable API key. When present, use `external_contract_id` to join an account to your system or `external_id` to reconcile source servicing data. Keep both optional identifiers as strings so formatting such as leading zeros is preserved. See the [generated OpenAPI contract](https://docs.montereyfinancial.com/api-reference/external_api.openapi.json) for the complete response schema.

## Resolve one account by a source identifier

Use an identifier lookup when your workflow starts with an account or contract ID from your system. Both endpoints return the same detailed account shape as `GET /v1/accounts/{id}`.

```bash theme={null}
curl -H "Authorization: Bearer $MFS_ACCESS_TOKEN" \
  "https://api.montereyfinancial.app/v1/accounts/by-external-id/12345"

curl -H "Authorization: Bearer $MFS_ACCESS_TOKEN" \
  "https://api.montereyfinancial.app/v1/accounts/by-external-contract-id/CONTRACT-12345"
```

If the identifier is unique within your token's organization allowlist, omit `organization_id`. If the API returns `409 ambiguous_identifier`, retry with the organization that owns the account:

```bash theme={null}
curl -G \
  -H "Authorization: Bearer $MFS_ACCESS_TOKEN" \
  --data-urlencode "organization_id=01K..." \
  "https://api.montereyfinancial.app/v1/accounts/by-external-contract-id/CONTRACT-12345"
```

An explicitly out-of-scope organization returns `403`. A missing or invisible identifier returns `404`. URL-encode identifier path segments before sending them.

## Enrich a borrower profile

Person lists are intentionally thin. Fetch [person detail](https://docs.montereyfinancial.com/api-reference/persons/get-a-person.md) only when your workflow needs contact or address enrichment.

```bash theme={null}
curl -H "Authorization: Bearer $MFS_ACCESS_TOKEN" \
  https://api.montereyfinancial.app/v1/persons/01J...
```

The API never returns an SSN hash or full SSN.

## Drill from organization to transactions

1. List accounts for an organization.
2. Select the accounts your workflow needs.
3. Fetch each account's transactions.

```bash theme={null}
curl -H "Authorization: Bearer $MFS_ACCESS_TOKEN" \
  "https://api.montereyfinancial.app/v1/accounts?organization_id=01K...&limit=500"

curl -H "Authorization: Bearer $MFS_ACCESS_TOKEN" \
  "https://api.montereyfinancial.app/v1/accounts/01J.../transactions?from=2026-01-01&to=2026-01-31&limit=500"
```

Omit `from` and `to` to retrieve the account's full transaction history. Keep following `next_cursor`; null-dated legacy transactions appear after dated transactions.

## Set up autopay

First list payment methods eligible for the account, then create the schedule.

```bash theme={null}
curl -H "Authorization: Bearer $MFS_ACCESS_TOKEN" \
  https://api.montereyfinancial.app/v1/accounts/01J.../payment-methods

curl -X POST \
  -H "Authorization: Bearer $MFS_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "account_id": "01J...",
    "payment_method_id": "01J...",
    "amount_cents": 25000,
    "frequency_unit": "month",
    "frequency_interval": 1,
    "start_date": "2026-09-01",
    "anchor_day": 1
  }' \
  https://api.montereyfinancial.app/v1/autopay
```

Only active payment methods returned by `/v1/accounts/{id}/payment-methods` are eligible. To change cadence or start date, cancel and recreate the schedule.

## Capture a card payment method

Use the secure proxy when you need to create a stored card from raw PAN and CVC. The full flow, request shape, and retry behavior are documented in [Card capture](https://docs.montereyfinancial.com/api-reference/card-capture.md).

> **[Card capture](https://docs.montereyfinancial.com/api-reference/card-capture.md)**
>
> Use the secure Basis Theory-backed proxy for card creation, idempotent retries, and billing-address selection.

## Backfill safely

* Split long date ranges into monthly windows.
* Persist `next_cursor` with your job state.
* Use `limit` values no greater than 1000.
* Upsert by stable Monterey IDs so retries do not duplicate rows.
* Read `Retry-After` on 429 responses and add jitter before retrying.


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