Books

A Book is the complete stored deal. It carries the deal’s identity, parse status, source, user edits, exclusions, and raw output from every parser that ran across its documents. Bank-statement data has several representations. Choosing one should be deliberate:

Data	Where it lives	What it contains
Complete Book	`GET /books/{book_id}`	Book fields and the entire `book_meta` object
Canonical raw bank result	Inside `book_meta`	Extracted business, owners, accounts, statement ledgers, transactions, and stored positions
Computed underwriting result	`GET /books/{book_id}/analytics`	Current metrics, normalized transactions, enriched positions, counterparties, and screening
Simple statement history	`GET /books/{book_id}/statements`	Accounts first, with their statements and daily balances nested underneath

Credit reports, tax forms, loan applications, photo IDs, and voided checks are also returned inside the full Book’s book_meta.

Get a Book

GET /books/{book_id}

import requests

API_BASE = "https://api.lendpathway.com/api"
TOKEN = "pat_your_token_here"
BOOK_ID = "99cc93e6-1f3f-42b1-9fe4-ba5a95be9c78"

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

book = response.json()
print(book["parse_status"], book["parse_status_message"])

const API_BASE = "https://api.lendpathway.com/api";
const TOKEN = "pat_your_token_here";
const BOOK_ID = "99cc93e6-1f3f-42b1-9fe4-ba5a95be9c78";

const response = await fetch(`${API_BASE}/books/${BOOK_ID}`, {
  headers: { Authorization: `Bearer ${TOKEN}` },
});

if (!response.ok) {
  throw new Error(`${response.status}: ${await response.text()}`);
}

const book = await response.json();
console.log(book.parse_status, book.parse_status_message);

curl --fail-with-body \
  "https://api.lendpathway.com/api/books/99cc93e6-1f3f-42b1-9fe4-ba5a95be9c78" \
  -H "Authorization: Bearer pat_your_token_here"

Parse status

parse_status follows this state flow:

Status	Meaning
`new`	The Book exists and has not started parsing
`processing`	Files are being uploaded, classified, or parsed
`completed`	Parsing finished. Available parser outputs are attached to `book_meta`
`failed`	Parsing could not finish. Inspect `parse_status_message` and document statuses
`cancelled`	A running parse was stopped

The API can complete a Book when one document-specific pipeline fails and another succeeds. Inspect the parser keys you need rather than assuming every uploaded document produced output.

Complete Book response

The following models describe the JSON returned by GET /books/{book_id}. This call returns the complete stored Book, including book_meta.

Book

from datetime import datetime
from typing import Any, Literal
from uuid import UUID

from pydantic import BaseModel, Field

ParseStatus = Literal["new", "processing", "completed", "failed", "cancelled"]
BookOrigin = Literal["email", "manual", "api", "lendsaas", "salesforce"]


class UserSummary(BaseModel):
    id: UUID
    name: str | None = None
    email: str | None = None
    picture: str | None = None


class EmailAddress(BaseModel):
    email: str
    name: str | None = None


class BookLineageMeta(BaseModel):
    origin: BookOrigin = "manual"
    sender_email: str | None = None
    sender_name: str | None = None
    originator_group_id: UUID | None = None
    email_thread_id: str | None = None
    additional_addresses: list[EmailAddress] = Field(default_factory=list)


class Book(BaseModel):
    id: UUID
    org_id: UUID | None = None
    parse_status: ParseStatus | None = "new"
    parse_status_message: str | None = None

    name: str
    description: str | None = None
    book_tag: str | None = None
    is_starred: bool = False
    is_deleted: bool = False
    created_by: UUID | None = None
    created_by_user: UserSummary | None = None
    created_at: datetime
    updated_at: datetime

    document_count: int | None = None  # deprecated
    book_meta: BookMeta = Field(default_factory=BookMeta)
    last_parsed_at: datetime | None = None
    parse_job_id: UUID | None = None

    email_thread_id: str | None = None
    salesforce_opportunity_id: str | None = None
    lendsaas_lead_id: str | None = None
    orgmeter_lead_id: str | None = None
    lineage_meta: BookLineageMeta = Field(default_factory=BookLineageMeta)

    is_legacy: bool = False
    notes: str | None = None
    eval_baseline: dict[str, Any] | None = None
    web_research_running: bool = False

BookMeta

from typing import Any

from pydantic import BaseModel, Field


class BookMeta(BaseModel):
    # Raw output written by the document-specific parsers
    parser_v2_mca_result: dict[str, Any] | None = None
    parser_v2_credit_report: dict[str, Any] | None = None
    parser_v2_tax_forms: dict[str, Any] | None = None
    parser_v2_loan_application: dict[str, Any] | None = None
    parser_v2_identity_documents: dict[str, Any] | None = None
    parser_v2_plaid_result: dict[str, Any] | None = None

    # Explicit user and organization configuration applied at analytics time
    excluded_document_ids: list[str] = Field(default_factory=list)
    excluded_account_ids: list[int] = Field(default_factory=list)
    excluded_position_ids: list[str] = Field(default_factory=list)
    revenue_exclusion_tags: list[str] | None = None
    selected_credit_bureau: str | None = None

Raw parser keys

Key	Content
`parser_v2_mca_result`	Uploaded bank statement extraction with businesses, accounts, statement ledgers, transactions, and stored debt positions
`parser_v2_plaid_result`	Plaid Asset Report data and its normalized bank-statement representation. When present, it is the canonical bank source
`parser_v2_credit_report`	Subject identity, bureau data, FICO scores, inquiries, and tradelines
`parser_v2_tax_forms`	Extracted 1040, Schedule C, 1065, 1120-S, and K-1 forms
`parser_v2_loan_application`	Fields extracted from the application, including requested amount and applicant information
`parser_v2_identity_documents`	Extracted photo ID and voided-check data

book_meta stores parser output and explicit edits. Computed metrics are generated when you call /analytics and are not stored here.

Canonical raw bank result

Bank data can arrive from uploaded statements or a Plaid Asset Report. Pathway uses the normalized Plaid result when it exists. Uploaded-statement output is the fallback.

book = requests.get(
    f"{API_BASE}/books/{BOOK_ID}",
    headers={"Authorization": f"Bearer {TOKEN}"},
    timeout=30,
).json()

meta = book["book_meta"]
plaid = meta.get("parser_v2_plaid_result") or {}
canonical_mca = plaid.get("holy_mca") or meta.get("parser_v2_mca_result")

if canonical_mca:
    print(canonical_mca["business"])
    print(canonical_mca["merged_accounts"])

merged_accounts is the most direct raw transaction view. It combines transactions from every statement by account number. bank_statements preserves the source-document and statement-period hierarchy.

Complete HolyMCAResult model

from typing import Any, Literal

from pydantic import BaseModel, Field


class PhoneNumber(BaseModel):
    country_code: str = "+1"
    area_code: str
    phone_number: str
    extension: str | None = None


class Address(BaseModel):
    country: str | None = None
    street_address: str | None = None
    street_address_line_2: str | None = None
    city: str | None = None
    state_province: str | None = None
    postal_code: str | None = None


class Human(BaseModel):
    full_name: str
    phone_number: PhoneNumber | None = None
    human_address: Address | None = None
    human_relationship_to_business: str | None = None


class Business(BaseModel):
    business_name: str
    legal_business_name: str | None = None
    business_phone_number: PhoneNumber | None = None
    business_address: Address | None = None


class AccountLedger(BaseModel):
    account_id: int
    account_name: str
    account_number: str
    account_type: str
    bank_name: str
    routing_number: str | None = None


class HolyTransaction(BaseModel):
    transaction_id: int | None = None
    document_id: str | None = None
    transaction_date: str | None = None
    description: str | None = None
    amount: float | None = None
    transaction_type: Literal["credit", "debit"] | str | None = None
    ledger_balance: float | None = None
    tag: list[str] | None = None
    position: dict[str, Any] | None = None


class ReconciliationResult(BaseModel):
    reconciled: bool = False
    reconciliation_skipped: bool = False
    attempts_made: int = 0
    sum_transactions: float = 0.0
    computed_ending_balance: float = 0.0
    expected_ending_balance: float = 0.0
    discrepancy: float = 0.0
    last_error: str | None = None


class HolyLedger(BaseModel):
    account_id: int | None = None
    account_name: str | None = None
    account_number: str | None = None
    account_type: str | None = None
    bank_name: str | None = None
    routing_number: str | None = None
    statement_starting_balance: float | None = None
    statement_ending_balance: float | None = None
    statement_num_credits: int | None = None
    statement_num_debits: int | None = None
    transactions: list[HolyTransaction] | None = None
    reconciliation_result: ReconciliationResult | None = None


class HolyBankStatement(BaseModel):
    document_id: str | None = None
    document_name: str | None = None
    document_type: str | None = None
    statement_start_date: str | None = None
    statement_end_date: str | None = None
    ledgers: list[HolyLedger] | None = None


class MergedMCAAccount(BaseModel):
    account_number: str | None = None
    account_name: str | None = None
    transactions: list[HolyTransaction] | None = None


class StoredPosition(BaseModel):
    position_id: str
    name: str | None = None
    loan_type: str = "merchant_cash_advance"
    transaction_ids: list[int] = Field(default_factory=list)
    funder_uuid: str | None = None
    funder_title: str | None = None
    funder_link: str | None = None
    funder_contact: str | None = None
    funder_email: str | None = None


class HolyMCAResult(BaseModel):
    business: Business | None = None
    humans: list[Human] | None = None
    account_ledgers: list[AccountLedger] | None = None
    bank_statements: list[HolyBankStatement] | None = None
    merged_accounts: dict[str, MergedMCAAccount] | None = None
    positions: list[StoredPosition] = Field(default_factory=list)
    total_disbursements: float = 0.0
    total_payments: float = 0.0
    transaction_count: int = 0
    web_research: str | None = None
    tampering_analysis: Any | None = None

These values reflect parser output and stored edits. For metrics such as true revenue, average daily balance, debt-to-income ratio, normalized position schedules, and screening decisions, request the full BookAnalytics.

A reparse replaces book_meta. Any manual transaction tags, debt-position edits, and exclusions on the existing parse are discarded.

List Books

GET /books/

Returns every active Book in the token’s organization, newest first.

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

for book in response.json():
    print(book["id"], book["name"], book["parse_status"])

The list endpoint deliberately returns book_meta as an empty object because raw parser output can be large. Fetch a specific Book when you need its full metadata.

Update Book fields

PATCH /books/{book_id}
Content-Type: application/json

Send only the fields you want to change. The supported content fields are name, description, book_tag, and notes.

response = requests.patch(
    f"{API_BASE}/books/{BOOK_ID}",
    headers={"Authorization": f"Bearer {TOKEN}"},
    json={
        "name": "Acme Coffee Renewal",
        "book_tag": "priority",
    },
    timeout=30,
)
response.raise_for_status()

The default response omits the large parser payload. Add ?include_meta=true when the updated response also needs the complete book_meta. DELETE /books/{book_id} soft-deletes the Book and cancels an active parse. POST /books/{book_id}/toggle-star toggles the starred state without sending a request body.

Read document-oriented results

The Book endpoint is the entry point for raw credit, tax, application, and identity output. Computed endpoints are available when you want normalized results:

Request	Use it for
`GET /books/{book_id}/analytics`	Bank metrics, enriched transactions, positions, cash-flow patterns, and screening
`GET /books/{book_id}/statements`	Account-first bank statement history with daily balances
`GET /books/{book_id}/tax-analytics`	Qualifying-income analysis across parsed tax years
`GET /books/{book_id}/csv-export`	Bank-underwriting CSV
`GET /books/{book_id}/spreadsheet-export`	Template-generated Excel or PDF

For transaction tags, debt positions, and underwriting exclusions, continue with Underwriting edits.

Response conditions

Status	Meaning
`401`	Missing or invalid PAT
`403`	The token cannot access this organization or Book
`404`	The Book does not exist in the token’s organization

Overview

Endpoints

Cookbook

Get a Book

Parse status

Complete Book response

Raw parser keys

Canonical raw bank result

List Books

Update Book fields

Read document-oriented results

Response conditions

​Get a Book

​Parse status

​Complete Book response

​Raw parser keys

​Canonical raw bank result

​List Books

​Update Book fields

​Read document-oriented results

​Response conditions

Get a Book

Parse status

Complete Book response

Raw parser keys

Canonical raw bank result

List Books

Update Book fields

Read document-oriented results

Response conditions