Integration patterns

These recipes assume you’ve read Authentication and Conventions — they cover the Bearer header, pagination shape (cursor/limit → next_cursor), money fields (integer cents), and error envelopes. Each recipe shows the same workflow in three forms: a one-line curl, a Python snippet, and a TypeScript snippet using built-in fetch with inline types. The host in every example is https://api.montereyfinancial.app. Replace mk_your_key_here with your real key.

Daily incremental sync

Pull yesterday’s new transactions into your warehouse. Anchor on the effective_at date range, paginate with cursor/limit, dedupe on transaction_id in your warehouse rather than tracking a high-water mark on the API side. Re-running the same window is safe — the API returns the same transaction IDs.

# Replace YESTERDAY with yesterday's date in UTC (e.g. 2026-05-27)
curl -H "Authorization: Bearer mk_your_key_here" \
  "https://api.montereyfinancial.app/transactions?from=YESTERDAY&to=YESTERDAY&limit=500"

# Then paginate by passing back next_cursor:
curl -H "Authorization: Bearer mk_your_key_here" \
  "https://api.montereyfinancial.app/transactions?from=YESTERDAY&to=YESTERDAY&limit=500&cursor=NEXT_CURSOR_VALUE"

import os
from datetime import date, timedelta

import httpx

API_KEY = os.environ["MFS_API_KEY"]
BASE = "https://api.montereyfinancial.app"
HEADERS = {"Authorization": f"Bearer {API_KEY}"}

def fetch_all(url: str, params: dict) -> list[dict]:
    items, cursor = [], None
    while True:
        if cursor:
            params["cursor"] = cursor
        resp = httpx.get(url, params=params, headers=HEADERS, timeout=30.0)
        resp.raise_for_status()
        page = resp.json()
        items.extend(page["items"])
        cursor = page["page"]["next_cursor"]
        if not cursor:
            return items

yesterday = (date.today() - timedelta(days=1)).isoformat()
transactions = fetch_all(
    f"{BASE}/transactions",
    {"from": yesterday, "to": yesterday, "limit": 500},
)
for tx in transactions:
    save_to_warehouse(tx)  # dedupe on tx["transaction_id"] in your DB

type TransactionRow = {
  transaction_id: string;
  organization_id: string;
  account_id: string;
  type: string;          // "payment" | "adjustment" | ...
  amount_cents: number;
  effective_at: string;  // YYYY-MM-DD
  status: string | null;
};
type PageMeta = { has_more: boolean; limit: number; next_cursor: string | null };
type TransactionsPage = { items: TransactionRow[]; page: PageMeta };

const API_KEY = process.env.MFS_API_KEY!;
const BASE = "https://api.montereyfinancial.app";

async function fetchAll(path: string, params: Record<string, string>): Promise<TransactionRow[]> {
  const items: TransactionRow[] = [];
  let cursor: string | null = null;
  do {
    const url = new URL(BASE + path);
    for (const [k, v] of Object.entries(params)) url.searchParams.set(k, v);
    if (cursor) url.searchParams.set("cursor", cursor);
    const res = await fetch(url, { headers: { Authorization: `Bearer ${API_KEY}` } });
    if (!res.ok) throw new Error(`${res.status} ${await res.text()}`);
    const data = (await res.json()) as TransactionsPage;
    items.push(...data.items);
    cursor = data.page.next_cursor;
  } while (cursor);
  return items;
}

const yesterday = new Date(Date.now() - 86_400_000).toISOString().slice(0, 10);
const transactions = await fetchAll("/transactions", {
  from: yesterday,
  to: yesterday,
  limit: "500",
});
for (const tx of transactions) {
  saveToWarehouse(tx); // dedupe on tx.transaction_id in your DB
}

Reconcile a payment to your books

This is the most concrete use of external_contract_number. Two directions: You see a payment in Monterey, want to find the matching record in your system. Fetch the account by ID, read external_contract_number, look up in your DB. You have a contract number in your system, want all Monterey transactions for it. List accounts filtered by your contract number (via list-and-filter, since there’s no ?external_contract_number= query parameter today), then list transactions per matching account.

# Direction 1: MFS payment → your contract number
# Given a transaction with account_id="01J..."
curl -H "Authorization: Bearer mk_your_key_here" \
  "https://api.montereyfinancial.app/accounts/01J..."
# → response includes external_contract_number; look that up in your DB

# Direction 2: your contract number → all MFS transactions for it
# First find the account (no direct filter; scan accounts list)
curl -H "Authorization: Bearer mk_your_key_here" \
  "https://api.montereyfinancial.app/accounts?limit=500"
# Filter locally for the account whose external_contract_number matches yours.
# Then list its transactions:
curl -H "Authorization: Bearer mk_your_key_here" \
  "https://api.montereyfinancial.app/accounts/01J.../transactions?limit=500"

import os
import httpx

API_KEY = os.environ["MFS_API_KEY"]
BASE = "https://api.montereyfinancial.app"
HEADERS = {"Authorization": f"Bearer {API_KEY}"}

def get_account(account_id: str) -> dict:
    r = httpx.get(f"{BASE}/accounts/{account_id}", headers=HEADERS, timeout=30.0)
    r.raise_for_status()
    return r.json()

def find_account_by_contract(your_contract_number: str) -> dict | None:
    # Walk accounts pages, filtering locally.
    cursor = None
    while True:
        params = {"limit": 500}
        if cursor:
            params["cursor"] = cursor
        r = httpx.get(f"{BASE}/accounts", params=params, headers=HEADERS, timeout=30.0)
        r.raise_for_status()
        page = r.json()
        for acct in page["items"]:
            if acct["external_contract_number"] == your_contract_number:
                return acct
        cursor = page["page"]["next_cursor"]
        if not cursor:
            return None

# Direction 1
account = get_account("01J...")
your_record = your_db.find_by_contract(account["external_contract_number"])

# Direction 2
account = find_account_by_contract("YOUR-CONTRACT-12345")
if account:
    tx_resp = httpx.get(
        f"{BASE}/accounts/{account['id']}/transactions",
        params={"limit": 500},
        headers=HEADERS,
        timeout=30.0,
    )
    transactions = tx_resp.json()["items"]

type AccountRow = {
  id: string;
  organization_id: string;
  external_contract_number: string | null;
  external_account_number: string | null;
  current_balance_cents: number;
  status_code: string;
};
type AccountsPage = { items: AccountRow[]; page: { next_cursor: string | null } };

const API_KEY = process.env.MFS_API_KEY!;
const BASE = "https://api.montereyfinancial.app";
const H = { Authorization: `Bearer ${API_KEY}` };

async function getAccount(accountId: string): Promise<AccountRow> {
  const res = await fetch(`${BASE}/accounts/${accountId}`, { headers: H });
  if (!res.ok) throw new Error(`${res.status}`);
  return (await res.json()) as AccountRow;
}

async function findAccountByContract(yourContractNumber: string): Promise<AccountRow | null> {
  let cursor: string | null = null;
  do {
    const url = new URL(`${BASE}/accounts`);
    url.searchParams.set("limit", "500");
    if (cursor) url.searchParams.set("cursor", cursor);
    const res = await fetch(url, { headers: H });
    if (!res.ok) throw new Error(`${res.status}`);
    const page = (await res.json()) as AccountsPage;
    const match = page.items.find(a => a.external_contract_number === yourContractNumber);
    if (match) return match;
    cursor = page.page.next_cursor;
  } while (cursor);
  return null;
}

// Direction 1
const account = await getAccount("01J...");
const yourRecord = yourDb.findByContract(account.external_contract_number);

// Direction 2
const found = await findAccountByContract("YOUR-CONTRACT-12345");
if (found) {
  const txRes = await fetch(`${BASE}/accounts/${found.id}/transactions?limit=500`, { headers: H });
  const transactions = (await txRes.json()).items;
}

Drill from organization → account → transaction

The resource-composition pattern. Useful for customer service tools and “everything about this customer” views. Three hops: pick an organization, list its accounts, then list a specific account’s transactions. For org-wide aggregates (total payments this month across all accounts), the Reports family is usually a better fit than walking the resource tree — the server-side aggregation is cheaper than fetching every row.

# 1. Get the organization (if you only have its id from a list response)
curl -H "Authorization: Bearer mk_your_key_here" \
  "https://api.montereyfinancial.app/organizations/01K..."

# 2. List all accounts in that organization
curl -H "Authorization: Bearer mk_your_key_here" \
  "https://api.montereyfinancial.app/accounts?organization_id=01K...&limit=500"

# 3. List transactions for one specific account
curl -H "Authorization: Bearer mk_your_key_here" \
  "https://api.montereyfinancial.app/accounts/01J.../transactions?limit=500"

import os
import httpx

API_KEY = os.environ["MFS_API_KEY"]
BASE = "https://api.montereyfinancial.app"
HEADERS = {"Authorization": f"Bearer {API_KEY}"}

def drill_org_to_transactions(organization_id: str) -> dict:
    org = httpx.get(
        f"{BASE}/organizations/{organization_id}", headers=HEADERS, timeout=30.0,
    ).json()

    accounts_resp = httpx.get(
        f"{BASE}/accounts",
        params={"organization_id": organization_id, "limit": 500},
        headers=HEADERS,
        timeout=30.0,
    ).json()
    accounts = accounts_resp["items"]

    transactions_by_account: dict[str, list[dict]] = {}
    for acct in accounts:
        tx_resp = httpx.get(
            f"{BASE}/accounts/{acct['id']}/transactions",
            params={"limit": 500},
            headers=HEADERS,
            timeout=30.0,
        ).json()
        transactions_by_account[acct["id"]] = tx_resp["items"]

    return {"organization": org, "accounts": accounts, "transactions": transactions_by_account}

result = drill_org_to_transactions("01K...")

type Organization = { id: string; display_name: string; legal_name: string; is_active: boolean };
type AccountRow = {
  id: string;
  organization_id: string;
  primary_borrower_party_id: string;
  external_contract_number: string | null;
  current_balance_cents: number;
  status_code: string;
};
type TransactionRow = {
  transaction_id: string;
  account_id: string;
  organization_id: string;
  type: string;
  amount_cents: number;
  effective_at: string;
};

const API_KEY = process.env.MFS_API_KEY!;
const BASE = "https://api.montereyfinancial.app";
const H = { Authorization: `Bearer ${API_KEY}` };

async function drillOrgToTransactions(organizationId: string) {
  const orgRes = await fetch(`${BASE}/organizations/${organizationId}`, { headers: H });
  const organization = (await orgRes.json()) as Organization;

  const acctsRes = await fetch(
    `${BASE}/accounts?organization_id=${organizationId}&limit=500`,
    { headers: H },
  );
  const accounts = ((await acctsRes.json()) as { items: AccountRow[] }).items;

  const transactionsByAccount: Record<string, TransactionRow[]> = {};
  for (const acct of accounts) {
    const txRes = await fetch(`${BASE}/accounts/${acct.id}/transactions?limit=500`, { headers: H });
    transactionsByAccount[acct.id] = ((await txRes.json()) as { items: TransactionRow[] }).items;
  }

  return { organization, accounts, transactions: transactionsByAccount };
}

const result = await drillOrgToTransactions("01K...");

Backfill historical data at scale

Walk a multi-year date range in monthly chunks. The pagination pattern is identical to the daily sync — just scaled up. Three operational notes:

Chunk by month, not year. Keeps individual jobs short enough to retry without losing too much state.
Save next_cursor between chunks. A multi-hour backfill that crashes shouldn’t restart from scratch — store the cursor in your job state and resume.
Respect the limit ceiling. The maximum limit is 1000; passing higher returns 422 (see Conventions).

# Pull one month at a time. Loop in shell or in your job runner.
for month in 2024-01 2024-02 2024-03; do
  from="${month}-01"
  to=$(date -d "${from} +1 month -1 day" +%F)
  cursor=""
  while :; do
    url="https://api.montereyfinancial.app/transactions?from=${from}&to=${to}&limit=500${cursor:+&cursor=$cursor}"
    resp=$(curl -s -H "Authorization: Bearer mk_your_key_here" "$url")
    echo "$resp" | jq -c '.items[]' >> backfill.jsonl
    cursor=$(echo "$resp" | jq -r '.page.next_cursor // empty')
    [ -z "$cursor" ] && break
  done
done

import os
from datetime import date
from dateutil.relativedelta import relativedelta  # pip install python-dateutil

import httpx

API_KEY = os.environ["MFS_API_KEY"]
BASE = "https://api.montereyfinancial.app"
HEADERS = {"Authorization": f"Bearer {API_KEY}"}

def backfill_transactions(start: date, end: date) -> None:
    month_start = start.replace(day=1)
    while month_start <= end:
        month_end = (month_start + relativedelta(months=1)) - relativedelta(days=1)
        cursor = None
        while True:
            params = {
                "from": month_start.isoformat(),
                "to": min(month_end, end).isoformat(),
                "limit": 500,
            }
            if cursor:
                params["cursor"] = cursor
            resp = httpx.get(
                f"{BASE}/transactions", params=params, headers=HEADERS, timeout=60.0,
            )
            resp.raise_for_status()
            page = resp.json()
            for row in page["items"]:
                save_to_warehouse(row)  # dedupe on transaction_id
            cursor = page["page"]["next_cursor"]
            if not cursor:
                break
        month_start += relativedelta(months=1)

backfill_transactions(date(2022, 1, 1), date.today())

type TransactionRow = {
  transaction_id: string;
  account_id: string;
  organization_id: string;
  type: string;
  amount_cents: number;
  effective_at: string;
};
type Page = { items: TransactionRow[]; page: { next_cursor: string | null } };

const API_KEY = process.env.MFS_API_KEY!;
const BASE = "https://api.montereyfinancial.app";
const H = { Authorization: `Bearer ${API_KEY}` };

function addMonths(d: Date, n: number): Date {
  const out = new Date(d);
  out.setUTCMonth(out.getUTCMonth() + n);
  return out;
}

async function backfillTransactions(start: Date, end: Date): Promise<void> {
  let monthStart = new Date(Date.UTC(start.getUTCFullYear(), start.getUTCMonth(), 1));
  while (monthStart <= end) {
    const monthEnd = new Date(addMonths(monthStart, 1).getTime() - 86_400_000);
    const windowEnd = monthEnd < end ? monthEnd : end;
    let cursor: string | null = null;
    do {
      const url = new URL(`${BASE}/transactions`);
      url.searchParams.set("from", monthStart.toISOString().slice(0, 10));
      url.searchParams.set("to", windowEnd.toISOString().slice(0, 10));
      url.searchParams.set("limit", "500");
      if (cursor) url.searchParams.set("cursor", cursor);
      const res = await fetch(url, { headers: H });
      if (!res.ok) throw new Error(`${res.status} ${await res.text()}`);
      const page = (await res.json()) as Page;
      for (const row of page.items) saveToWarehouse(row); // dedupe on transaction_id
      cursor = page.page.next_cursor;
    } while (cursor);
    monthStart = addMonths(monthStart, 1);
  }
}

await backfillTransactions(new Date("2022-01-01"), new Date());

Set up autopay on an account

The first write-surface recipe: attach a recurring payment schedule to an account. Two calls — find an eligible stored payment method, then create the schedule. GET /accounts/{id}/payment-methods returns exactly the methods that can fund autopay for that account: they belong to a borrower on the account, and only active methods are included (deactivated ones appear only in the top-level /payment-methods list). No filtering needed on your side. The example pins a monthly charge to the 1st using anchor_day. For cadences like “every two weeks,” use frequency_unit: "week" with frequency_interval: 2 and no anchor.

# 1. List payment methods eligible for this account
curl -H "Authorization: Bearer mk_your_key_here" \
  "https://api.montereyfinancial.app/accounts/01J.../payment-methods"
# Every method returned is active and eligible — pick one.

# 2. Create the schedule: 25,000 cents on the 1st of every month
curl -X POST \
  -H "Authorization: Bearer mk_your_key_here" \
  -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-07-01",
    "anchor_day": 1
  }' \
  "https://api.montereyfinancial.app/autopay"
# → 201 with the created schedule, including next_run_date.

# Later: pause, resume, or cancel
curl -X PATCH -H "Authorization: Bearer mk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{"status": "paused"}' \
  "https://api.montereyfinancial.app/autopay/01J..."
curl -X DELETE -H "Authorization: Bearer mk_your_key_here" \
  "https://api.montereyfinancial.app/autopay/01J..."

import os
import httpx

API_KEY = os.environ["MFS_API_KEY"]
BASE = "https://api.montereyfinancial.app"
HEADERS = {"Authorization": f"Bearer {API_KEY}"}

def setup_autopay(account_id: str, amount_cents: int, start_date: str) -> dict:
    # 1. Find a payment method eligible for this account (only active ones are returned)
    pm_resp = httpx.get(
        f"{BASE}/accounts/{account_id}/payment-methods",
        headers=HEADERS,
        timeout=30.0,
    )
    pm_resp.raise_for_status()
    methods = pm_resp.json()["items"]
    if not methods:
        raise RuntimeError("No active payment method on file for this account")

    # 2. Create the schedule: monthly, pinned to the 1st
    create_resp = httpx.post(
        f"{BASE}/autopay",
        json={
            "account_id": account_id,
            "payment_method_id": methods[0]["id"],
            "amount_cents": amount_cents,
            "frequency_unit": "month",
            "frequency_interval": 1,
            "start_date": start_date,
            "anchor_day": 1,
        },
        headers=HEADERS,
        timeout=30.0,
    )
    create_resp.raise_for_status()
    return create_resp.json()  # includes next_run_date and status

schedule = setup_autopay("01J...", amount_cents=25000, start_date="2026-07-01")

# Later: pause / resume / cancel
httpx.patch(f"{BASE}/autopay/{schedule['id']}", json={"status": "paused"}, headers=HEADERS, timeout=30.0)
httpx.patch(f"{BASE}/autopay/{schedule['id']}", json={"status": "active"}, headers=HEADERS, timeout=30.0)
httpx.delete(f"{BASE}/autopay/{schedule['id']}", headers=HEADERS, timeout=30.0)  # cannot be undone

type PaymentMethodRow = {
  id: string;
  party_id: string;
  instrument_type: "card" | "bank_account" | "wallet";
  nickname: string | null;
  last_four: string;
  is_active: boolean;
};
type AutopayRow = {
  id: string;
  account_id: string;
  payment_method_id: string;
  amount_cents: number;
  frequency_unit: "day" | "week" | "month" | "year";
  frequency_interval: number;
  start_date: string;
  next_run_date: string;
  status: "active" | "paused" | "cancelled" | "expired";
};

const API_KEY = process.env.MFS_API_KEY!;
const BASE = "https://api.montereyfinancial.app";
const H = { Authorization: `Bearer ${API_KEY}` };

async function setupAutopay(accountId: string, amountCents: number, startDate: string): Promise<AutopayRow> {
  // 1. Find a payment method eligible for this account (only active ones are returned)
  const pmRes = await fetch(`${BASE}/accounts/${accountId}/payment-methods`, { headers: H });
  if (!pmRes.ok) throw new Error(`${pmRes.status} ${await pmRes.text()}`);
  const methods = ((await pmRes.json()) as { items: PaymentMethodRow[] }).items;
  const method = methods[0];
  if (!method) throw new Error("No active payment method on file for this account");

  // 2. Create the schedule: monthly, pinned to the 1st
  const createRes = await fetch(`${BASE}/autopay`, {
    method: "POST",
    headers: { ...H, "Content-Type": "application/json" },
    body: JSON.stringify({
      account_id: accountId,
      payment_method_id: method.id,
      amount_cents: amountCents,
      frequency_unit: "month",
      frequency_interval: 1,
      start_date: startDate,
      anchor_day: 1,
    }),
  });
  if (!createRes.ok) throw new Error(`${createRes.status} ${await createRes.text()}`);
  return (await createRes.json()) as AutopayRow;
}

const schedule = await setupAutopay("01J...", 25000, "2026-07-01");

// Later: pause / resume / cancel
await fetch(`${BASE}/autopay/${schedule.id}`, {
  method: "PATCH",
  headers: { ...H, "Content-Type": "application/json" },
  body: JSON.stringify({ status: "paused" }),
});
await fetch(`${BASE}/autopay/${schedule.id}`, { method: "DELETE", headers: H }); // cannot be undone

Operational notes:

Updating a schedule can change the payment method, amount, end date, or pause state. Cadence and start_date are fixed — cancel and recreate to change them.
Removing a payment method that an active or paused schedule still uses returns 409 — cancel the schedule first.
One-time payments (POST /payments) share this shape — account, payment method, amount — but aren’t live yet; every request returns 501 until submission ships.

Choosing reports vs resource endpoints

The Reporting API surface has two answer shapes — pre-shaped Reports and composable resource endpoints. They cover the same underlying data; the right choice depends on the shape of your question.

Your question	Use
”Give me all NSF returns in March.”	`GET /reports/nsfr`
”What payments came in yesterday?”	`GET /reports/crr` or `GET /transactions`
”What’s account `01J…` worth right now?”	`GET /accounts/{id}`
”Who is the primary borrower on account `01J…`?”	`GET /accounts/{id}` (includes `primary_borrower_party_id`)
“Show every transaction for borrower `01K…`.”	`GET /persons/{id}/accounts` → fan out to `/accounts/{id}/transactions`
”All write-offs this quarter, grouped by organization.”	`GET /reports/wor` (already returns `organization_id` per row)
“Recent activity on this one account.”	`GET /accounts/{id}/transactions`
”Reconcile all your contracts against MFS this month.”	`GET /reports/crr` (filter locally by `external_contract_number`)

Heuristics:

If the question is a row-shaped business answer (“payments”, “returns”, “balances”), there’s probably a report for it.
If the question is about a specific entity (“this account”, “this person”), use the resource endpoints.
If the question is “everything about X”, drill from the resource endpoint.
When in doubt, reports are less code — they pre-filter on the server, so you write less pagination code on your side.

Getting started

Core concepts

How-to guides

Daily incremental sync

Reconcile a payment to your books

Drill from organization → account → transaction

Backfill historical data at scale

Set up autopay on an account

Choosing reports vs resource endpoints

​Daily incremental sync

​Reconcile a payment to your books

​Drill from organization → account → transaction

​Backfill historical data at scale

​Set up autopay on an account

​Choosing reports vs resource endpoints

Daily incremental sync

Reconcile a payment to your books

Drill from organization → account → transaction

Backfill historical data at scale

Set up autopay on an account

Choosing reports vs resource endpoints