Integration patterns

These examples assume you have exchanged your API key for an access token as described in Authentication. 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.

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.

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

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:

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 only when your workflow needs contact or address enrichment.

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

List accounts for an organization.
Select the accounts your workflow needs.
Fetch each account’s transactions.

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.

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.

Card capture

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.

Getting started

Core concepts

How-to guides

Daily transaction sync

Ingest accounts and borrower roles

Resolve one account by a source identifier

Enrich a borrower profile

Drill from organization to transactions

Set up autopay

Capture a card payment method

Card capture

Backfill safely

​Daily transaction sync

​Ingest accounts and borrower roles

​Resolve one account by a source identifier

​Enrich a borrower profile

​Drill from organization to transactions

​Set up autopay

​Capture a card payment method

Card capture

​Backfill safely

Daily transaction sync

Ingest accounts and borrower roles

Resolve one account by a source identifier

Enrich a borrower profile

Drill from organization to transactions

Set up autopay

Capture a card payment method

Backfill safely