Work with analytics

GET /books/{book_id}/analytics is the main underwriting response for bank data. It contains Book totals, monthly account rows, enriched transactions, detected debt positions, payment schedules, counterparty clusters, and screening. The response is computed when you request it. Changes to tags, exclusions, organization settings, or screening rules appear on the next call.

The complete typed contract is on the Analytics endpoint page. Keep that model beside your integration rather than recreating response fields from examples.

Fetch and validate the response

import os

import requests

API_BASE = "https://api.lendpathway.com/api"
TOKEN = os.environ["PATHWAY_API_TOKEN"]
BOOK_ID = "99cc93e6-1f3f-42b1-9fe4-ba5a95be9c78"

response = requests.get(
    f"{API_BASE}/books/{BOOK_ID}/analytics",
    headers={"Authorization": f"Bearer {TOKEN}"},
    timeout=60,
)
response.raise_for_status()
analytics = response.json()

If you copied the Pydantic contracts from the endpoint reference into pathway_models.py, validate at the boundary:

from pathway_models import BookAnalytics

analytics = BookAnalytics.model_validate(response.json())
print(analytics.true_revenue)

Validation catches a changed or unexpected payload before it moves into a credit decision, spreadsheet, or CRM field.

Start with the Book totals

The most commonly used fields are already calculated.

summary = {
    "total_deposits": analytics["total_deposits"],
    "total_withdrawals": analytics["total_withdrawals"],
    "true_revenue": analytics["true_revenue"],
    "average_daily_balance": analytics["average_daily_balance"],
    "days_negative": analytics["days_negative_balance"],
    "loan_payments": analytics["total_loan_payments"],
    "debt_to_income_ratio": analytics["debt_to_income_ratio"],
    "active_mca_positions": analytics["num_active_mca_positions"],
    "missed_payments": analytics["num_missed_payments"],
}

Do not recompute these values from raw book_meta. The analytics response has already applied the Book’s excluded documents, accounts, positions, and revenue tags, along with organization-level business-day settings.

Gross deposits and true revenue

total_deposits includes every credit. It can contain transfers, loan proceeds, owner contributions, reversals, and operating revenue. true_revenue includes credits that survive the active revenue-exclusion rules. The exact tag set used for the request appears in revenue_exclusion_tags.

print("Gross deposits", analytics["total_deposits"])
print("True revenue", analytics["true_revenue"])
print("Excluded tags", analytics["revenue_exclusion_tags"])

Debt-to-income ratio

Pathway returns debt_to_income_ratio as a percentage. A value of 18.4 means 18.4%. The value can be null when there is no qualifying revenue denominator.

dti = analytics["debt_to_income_ratio"]
if dti is None:
    print("DTI unavailable")
else:
    print(f"DTI {dti:.1f}%")

Read statement periods

statements is chronological bank data organized by statement period. Each period contains one or more account rows.

for statement in analytics["statements"]:
    print(
        statement["statement_period"],
        statement["statement_start_date"],
        statement["statement_end_date"],
    )

    for account in statement["accounts"]:
        print(
            account["account_id"],
            account["account_name"],
            account["true_revenue"],
            account["average_daily_balance"],
        )

Banks sometimes issue separate PDFs for each account in the same month. Pathway folds those files into one statement period and lists every source in document_ids.

Use the combined row for monthly trends

The row with account_id == 0 represents the combined cash position across included accounts for that statement period.

monthly = []

for statement in analytics["statements"]:
    combined = next(
        account
        for account in statement["accounts"]
        if account["account_id"] == 0
    )

    monthly.append({
        "period": statement["statement_period"],
        "deposits": combined["total_deposits"],
        "true_revenue": combined["true_revenue"],
        "average_daily_balance": combined["average_daily_balance"],
        "days_negative": combined["days_negative_balance"],
        "dti": combined["debt_to_income_ratio"],
    })

Use individual rows when the decision needs account-level detail. Avoid summing the combined row together with its individual account rows because that counts the same activity twice. average_statement_metrics contains the average period row used by Pathway’s tables and CSV export.

Read transactions

merged_accounts contains the normalized transaction history. It is keyed by account ID as a string.

transactions = [
    transaction
    for account in analytics["merged_accounts"].values()
    for transaction in account["transactions"]
]

transactions.sort(key=lambda transaction: transaction["transaction_date"])

Each transaction includes its bank description, direction, amount, running balance, cleaned tags, source document, and attached debt position when one exists.

Find true revenue credits

revenue_transactions = [
    transaction
    for transaction in transactions
    if "true_revenue" in transaction.get("tag", [])
]

for transaction in revenue_transactions[:20]:
    print(
        transaction["transaction_date"],
        transaction["description"],
        transaction["amount"],
    )

Find loan payments

Use the tags returned by GET /parse/tags when you need a complete dynamic tag registry. For a single response, position attachment is a clean way to isolate identified debt activity:

position_payments = [
    transaction
    for transaction in transactions
    if transaction["transaction_type"] == "debit"
    and transaction.get("position") is not None
]

Group by tag

A transaction can carry several tags. Decide whether your output is multi-label before aggregating.

from collections import defaultdict

totals_by_tag = defaultdict(float)

for transaction in transactions:
    for tag in transaction.get("tag", []):
        totals_by_tag[tag] += transaction["amount"]

for tag, total in sorted(totals_by_tag.items()):
    print(tag, round(total, 2))

The totals across tags will usually exceed deposits plus withdrawals because one transaction can contribute to more than one tag.

Read debt positions

Each object in positions represents one detected relationship with a lender or funder.

for position in analytics["positions"]:
    print({
        "name": position["funder_title"] or position["name"],
        "type": position["loan_type"],
        "status": position["status"],
        "funded": position["total_disbursements"],
        "paid": position["total_payments"],
        "daily_remit": position["daily_remit_burden"],
        "monthly_remit": position["monthly_remit_burden"],
        "holdback_pct": position["holdback_pct"],
        "misses": len(position["potential_missed_payments"]),
        "modifications": len(position["potential_modified_payments"]),
    })

status is just_funded, active, or closed. The episodes tree gives the history behind that rollup:

An initial episode begins the observed relationship.
A renewal begins after earlier schedules have closed.
A stack begins while an earlier schedule is still active.
An orphan contains payments whose advance occurred before the available statement window.

Payment schedules inside each episode include cadence, expected daily remittance, active state, inferred misses, and amount modifications.

for position in analytics["positions"]:
    for episode in position["episodes"]:
        for schedule in episode["schedules"]:
            print(
                position["name"],
                episode["role"],
                schedule["frequency"],
                schedule["avg_amount"],
                schedule["state"],
            )

Read counterparties

counterparty_clusters groups similar transaction descriptions separately for credits and debits.

top_credit_sources = sorted(
    (
        cluster
        for cluster in analytics["counterparty_clusters"]
        if cluster["direction"] == "credit"
    ),
    key=lambda cluster: cluster["total"],
    reverse=True,
)

for cluster in top_credit_sources[:10]:
    print(cluster["counterparty"], cluster["total"], cluster["count"])

Use transaction_ids to trace any cluster back to the underlying activity in merged_accounts.

Read screening

When organization screening is enabled, the response includes the complete fact sheet and current result.

result = analytics.get("screening_result")

if result:
    print(result["result"])

    for rule in result["resolved_rules"]:
        print(
            rule["result"],
            rule["reason"],
            rule["rule_after_substituting"],
        )

screening_metrics contains the normalized values available to rules, including recent-month snapshots, recency measures, applicant facts, and payment-risk counts. Missing facts remain null. Screening is evaluated during the analytics request. A rule update affects the next response without reparsing the Book.

Build an integration payload

Keep the Pathway response available for audit and map only the fields the receiving system understands.

def crm_payload(book: dict, analytics: dict) -> dict:
    screening = analytics.get("screening_result")

    return {
        "external_book_id": book["id"],
        "business_name": book["name"],
        "parse_status": book["parse_status"],
        "total_deposits": analytics["total_deposits"],
        "true_revenue": analytics["true_revenue"],
        "average_daily_balance": analytics["average_daily_balance"],
        "days_negative": analytics["days_negative_balance"],
        "debt_to_income_ratio": analytics["debt_to_income_ratio"],
        "active_mca_positions": analytics["num_active_mca_positions"],
        "monthly_mca_remit": analytics["total_mca_monthly_remit"],
        "screening_result": screening["result"] if screening else None,
    }

Store the Book ID with the destination record. It provides a stable path back to source documents, raw parser output, and refreshed analytics.

Overview

Endpoints

Cookbook

Work with analytics

Fetch and validate the response

Start with the Book totals

Gross deposits and true revenue

Debt-to-income ratio

Read statement periods

Use the combined row for monthly trends

Read transactions

Find true revenue credits

Find loan payments

Group by tag

Read debt positions

Read counterparties

Read screening

Build an integration payload

​Fetch and validate the response

​Start with the Book totals

​Gross deposits and true revenue

​Debt-to-income ratio

​Read statement periods

​Use the combined row for monthly trends

​Read transactions

​Find true revenue credits

​Find loan payments

​Group by tag

​Read debt positions

​Read counterparties

​Read screening

​Build an integration payload

Fetch and validate the response

Start with the Book totals

Gross deposits and true revenue

Debt-to-income ratio

Read statement periods

Use the combined row for monthly trends

Read transactions

Find true revenue credits

Find loan payments

Group by tag

Read debt positions

Read counterparties

Read screening

Build an integration payload