> This page is for API. > For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://docs.spreadspace.app/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.spreadspace.app/_mcp/server. # List all bank statements GET https://api.spreadspace.app/api/borrowers/{borrower_id}/extractions/bank-statements Lists every usable bank statement on the borrower's file. Duplicates and failed extractions are left out, and you can pass `loan_id` to narrow the list to one loan. Requires the `extractions:read` scope. Rate limit: 200 requests per minute per key (the `api` lane). Reference: https://docs.spreadspace.app/api/api-reference/bank-statements/get-bank-statements ## Authentication - `Authorization` header (bearer token, required) — Bearer token. Use `ss_live_…` for live data or `ss_test_…` for the sandbox (test mode). See [Authentication](https://docs.spreadspace.app/api/authentication). ## Request ### Path parameters - `borrower_id` (string, required) — The borrower's id. ### Query parameters - `loan_id` (string, optional) — Narrow the list to one loan. ### Headers - `SpreadSpace-Version` (string, optional) — Pin the API version, e.g. `2026-10-07`. Omit to get the latest. See [Versioning](https://docs.spreadspace.app/api/versioning). ## Response ### 200 OK - `borrower_id` (string, required) — The borrower the documents belong to. - `statements` (list of BankStatementReportDataListItem, required) — One row per document. ## Errors ### 400 Bad Request Error Bad request: validation failed, the cursor is malformed, or the API version is unknown. - `error` (ApiErrorBody, required) — Inner body of the canonical API error envelope. ### 401 Unauthorized Error Unauthorized: the bearer token or API key is missing or invalid. - `error` (ApiErrorBody, required) — Inner body of the canonical API error envelope. ### 402 Payment Required Error Payment required: the standard error envelope with `type` `subscription_required` when the workspace has no active or trialing subscription, or `billing_required` where a plan entitlement applies. - `error` (ApiErrorBody, required) — Inner body of the canonical API error envelope. ### 403 Forbidden Error Forbidden: authentication succeeded but the caller is not permitted to perform this action, for example an API key missing the required scope, an embed session reaching a loan it was not minted for, or a feature outside the workspace's plan. - `error` (ApiErrorBody, required) — Inner body of the canonical API error envelope. ### 404 Not Found Error Not found: the resource does not exist or is not visible to the calling tenant. - `error` (ApiErrorBody, required) — Inner body of the canonical API error envelope. ### 429 Too Many Requests Error Too many requests: the rate limit was hit, or an idempotency-key replay is still in progress. - `error` (ApiErrorBody, required) — Inner body of the canonical API error envelope. ### 500 Internal Server Error Internal server error: an unexpected failure. Quote the `request_id` in support tickets. A mutation sent with an `Idempotency-Key` replays this fault under that key rather than re-running; confirm the resource state before resending with a new key. - `error` (ApiErrorBody, required) — Inner body of the canonical API error envelope. ## Types ### BankStatementReportDataListItem One row of the Bank Statement list: the document's identity and its extracted object. - `extracted_document_id` (string, required) — Identifier of the extracted document. - `report_data` (Bank Statement, required) — The extracted object, in the family's shape. ### ApiErrorBody Inner body of the canonical API error envelope. - `type` (string, required) — Stable error type identifier. Pattern-match on this value, not the human-readable message. - `message` (string, required) — Human-readable error message. Subject to wording changes; do not parse. - `request_id` (string, optional, nullable) — Per-request correlation ID (matches `X-Request-ID` response header). Quote in support tickets. - `details` (map from string to string, optional, nullable) — Structured detail. Some error types populate documented keys in every environment: a version conflict (409) carries `current_version`, the version the resource is actually at, so the client can reload and re-apply. Free-form diagnostic detail beyond those keys appears in development environments only. An `insufficient_credits` 402 carries `balance_usd`, `reserved_usd`, `in_flight_docs`, `incoming_docs` and `per_doc_reservation_usd` as decimal strings. ### Bank Statement A business bank statement: the account, the statement period, the balance summary, one entry per day, and every transaction. Money is a decimal string with two decimals, in dollars. - `reportType` ("bank_statement_analysis", required) — Always bank_statement_analysis. - `account` (BankStatementReportData_BankStatementAccount, required) — The account the statement is for. - `period` (BankStatementReportData_BankStatementPeriod, required) — The statement period with its opening and closing balances. - `metrics` (BankStatementReportData_BankStatementMetrics, required) — Totals over the statement period. - `dailyBalances` (list of BankStatementReportData_BankDailyBalance, required) — One entry per day of the period. - `transactions` (list of BankStatementReportData_BankTransaction, required) — Every transaction, in statement order. - `period_source` (string, optional) — Whether the statement prints both ends of its period (`declared`) or at least one end is a date stated elsewhere in the statement's own text (`statement_text`); absent when the statement states no period. - `balance_source` (string, optional) — Where the period balances come from when the statement prints none: the linked account's current balance carried back through its own posted transactions, or the account's daily balances when the feed carries them (`feed_balance`); absent when the statement prints its balances. - `underwritingFlags` (list of BankStatementReportData_UnderwritingFlag, optional) — Notes about fees, returned items and other events in the transactions, when any. ### BankStatementReportData_BankStatementAccount The account the statement is for. - `holder` (string, required, nullable) — Name of the account holder as printed. - `institution` (string, required, nullable) — Name of the bank as printed. - `accountNumberLast4` (string, required, nullable) — The last four digits of the account number. - `type` (string, required, nullable) — The account type as printed, for example checking or savings. - `linkedAccountLast4` (list of string, optional) — Last four digits of the other accounts that appear on a statement covering several accounts. Empty for a statement of one account. ### BankStatementReportData_BankStatementPeriod The statement period and its opening and closing balances. - `start` (string, required, nullable) — First day of the statement period. - `end` (string, required, nullable) — Last day of the statement period. - `openingBalance` (string, required, nullable) — Balance at the start of the period, as printed; for a statement that prints none, the linked account's current balance carried back through its own transactions. - `closingBalance` (string, required, nullable) — Balance at the end of the period, as printed; for a statement that prints none, the linked account's current balance carried back through its own transactions. ### BankStatementReportData_BankStatementMetrics Totals over the statement period. - `totalDeposits` (string, required, nullable) — Total deposits. - `totalWithdrawals` (string, required, nullable) — Total withdrawals. - `netCashFlow` (string, required, nullable) — Deposits less withdrawals. - `transactionCount` (integer, required) — Number of transactions. - `avgDailyBalance` (string, optional, nullable) — Average of the daily closing balances; null when the period's opening balance is null. - `minDailyBalance` (string, optional, nullable) — Lowest daily closing balance; null when the period's opening balance is null. - `maxDailyBalance` (string, optional, nullable) — Highest daily closing balance; null when the period's opening balance is null. - `daysNegative` (integer, optional, nullable) — Number of days the closing balance was below zero; null when the period's opening balance is null. ### BankStatementReportData_BankDailyBalance One day of the statement period. - `date` (string, required) — The day. - `closing` (string, required, nullable) — Closing balance for the day; null when the period's opening balance is null. - `opening` (string, optional, nullable) — Opening balance for the day; null when the period's opening balance is null. - `deposits` (string, optional, nullable) — Total deposits for the day. - `withdrawals` (string, optional, nullable) — Total withdrawals for the day. - `transactionCount` (integer, optional) — Number of transactions posted that day. - `low_cash` (boolean, optional) — True when the day's closing balance is low relative to the statement's other balances. ### BankStatementReportData_BankTransaction One posted transaction. - `date` (string, required) — Posting date. - `description` (string, required) — The description as printed. - `amount` (string, required) — Signed amount: deposits positive, withdrawals negative. - `checkNumber` (string, optional, nullable) — Check number, when the transaction is a check. - `transactionType` (string, optional) — The transaction's kind: check, ach, wire, transfer, debit_card, fee, interest, atm, deposit or other. - `lineOrder` (integer, optional) — Position of the transaction on the statement, in posting order. - `accountLast4` (string, optional) — Last four digits of the account the transaction posted to, on a feed that carries several accounts. ### BankStatementReportData_UnderwritingFlag A note about events in the transactions: fees, returned items, overdrafts. - `category` (string, required) — The note's category. - `severity` (enum, required) — One of high, medium or low. - Allowed values: `high`, `medium`, `low` - `code` (string, required) — The note's identifier. - `message_customer` (string, required) — The note in words. - `field_ref` (string, required, nullable) — The field the note refers to, when it refers to one. - `detail` (BankStatementReportData_UnderwritingFlagDetail, optional) — The transactions behind the note. ### BankStatementReportData_UnderwritingFlagDetail The transactions behind a note. - `count` (integer, optional) — Number of matching transactions. - `total_amount` (string, optional) — Their amounts added together. - `matches` (list of BankStatementReportData_UnderwritingFlagMatch, optional) — The matching transactions. ### BankStatementReportData_UnderwritingFlagMatch One transaction behind a note. - `date` (string, required) — Posting date. - `description` (string, required) — The description as printed. - `amount` (string, required) — Signed amount: deposits positive, withdrawals negative. ## Examples **Response** ```json { "borrower_id": "3f9c2b1e8d7a4c5b9e0f1a2b", "statements": [ { "extracted_document_id": "7a1d4e9c2b3f4a5d8e6c1b0f", "report_data": { "reportType": "bank_statement_analysis", "account": { "holder": "Greenfield Construction LLC", "institution": "Wells Fargo", "accountNumberLast4": "5382", "type": "Commercial Banking" }, "period": { "start": "2025-01-01", "end": "2025-01-31", "openingBalance": "385000.00", "closingBalance": "395000.00" }, "metrics": { "totalDeposits": "565000.00", "totalWithdrawals": "555000.00", "netCashFlow": "10000.00", "transactionCount": 26, "avgDailyBalance": "378660.04", "minDailyBalance": "208972.55", "maxDailyBalance": "556460.24", "daysNegative": 0 }, "dailyBalances": [ { "date": "2025-01-01", "closing": "442226.68", "opening": "385000.00", "deposits": "128986.06", "withdrawals": "71759.38", "transactionCount": 3 }, { "date": "2025-01-02", "closing": "428281.63", "opening": "442226.68", "deposits": "0.00", "withdrawals": "13945.05", "transactionCount": 1 }, { "date": "2025-01-03", "closing": "416204.28", "opening": "428281.63", "deposits": "0.00", "withdrawals": "12077.35", "transactionCount": 1 }, { "date": "2025-01-04", "closing": "412155.47", "opening": "416204.28", "deposits": "0.00", "withdrawals": "4048.81", "transactionCount": 1 }, { "date": "2025-01-05", "closing": "412155.47", "opening": "412155.47", "deposits": "0.00", "withdrawals": "0.00", "transactionCount": 0 }, { "date": "2025-01-06", "closing": "410546.24", "opening": "412155.47", "deposits": "0.00", "withdrawals": "1609.23", "transactionCount": 1 }, { "date": "2025-01-07", "closing": "410546.24", "opening": "410546.24", "deposits": "0.00", "withdrawals": "0.00", "transactionCount": 0 }, { "date": "2025-01-08", "closing": "421422.31", "opening": "410546.24", "deposits": "56744.55", "withdrawals": "45868.48", "transactionCount": 2 }, { "date": "2025-01-09", "closing": "413824.15", "opening": "421422.31", "deposits": "0.00", "withdrawals": "7598.16", "transactionCount": 1 }, { "date": "2025-01-10", "closing": "388119.90", "opening": "413824.15", "deposits": "0.00", "withdrawals": "25704.25", "transactionCount": 2 }, { "date": "2025-01-11", "closing": "388119.90", "opening": "388119.90", "deposits": "0.00", "withdrawals": "0.00", "transactionCount": 0 }, { "date": "2025-01-12", "closing": "379242.36", "opening": "388119.90", "deposits": "0.00", "withdrawals": "8877.54", "transactionCount": 1 }, { "date": "2025-01-13", "closing": "367908.90", "opening": "379242.36", "deposits": "0.00", "withdrawals": "11333.46", "transactionCount": 1 }, { "date": "2025-01-14", "closing": "367908.90", "opening": "367908.90", "deposits": "0.00", "withdrawals": "0.00", "transactionCount": 0 }, { "date": "2025-01-15", "closing": "272360.85", "opening": "367908.90", "deposits": "0.00", "withdrawals": "95548.05", "transactionCount": 1 }, { "date": "2025-01-16", "closing": "272360.85", "opening": "272360.85", "deposits": "0.00", "withdrawals": "0.00", "transactionCount": 0 }, { "date": "2025-01-17", "closing": "270718.72", "opening": "272360.85", "deposits": "0.00", "withdrawals": "1642.13", "transactionCount": 1 }, { "date": "2025-01-18", "closing": "270718.72", "opening": "270718.72", "deposits": "0.00", "withdrawals": "0.00", "transactionCount": 0 }, { "date": "2025-01-19", "closing": "211200.04", "opening": "270718.72", "deposits": "0.00", "withdrawals": "59518.68", "transactionCount": 1 }, { "date": "2025-01-20", "closing": "208972.55", "opening": "211200.04", "deposits": "0.00", "withdrawals": "2227.49", "transactionCount": 1 }, { "date": "2025-01-21", "closing": "208972.55", "opening": "208972.55", "deposits": "0.00", "withdrawals": "0.00", "transactionCount": 0 }, { "date": "2025-01-22", "closing": "337852.68", "opening": "208972.55", "deposits": "128880.13", "withdrawals": "0.00", "transactionCount": 1 }, { "date": "2025-01-23", "closing": "310728.45", "opening": "337852.68", "deposits": "0.00", "withdrawals": "27124.23", "transactionCount": 1 }, { "date": "2025-01-24", "closing": "310728.45", "opening": "310728.45", "deposits": "0.00", "withdrawals": "0.00", "transactionCount": 0 }, { "date": "2025-01-25", "closing": "556460.24", "opening": "310728.45", "deposits": "250389.26", "withdrawals": "4657.47", "transactionCount": 2 }, { "date": "2025-01-26", "closing": "505744.93", "opening": "556460.24", "deposits": "0.00", "withdrawals": "50715.31", "transactionCount": 1 }, { "date": "2025-01-27", "closing": "505744.93", "opening": "505744.93", "deposits": "0.00", "withdrawals": "0.00", "transactionCount": 0 }, { "date": "2025-01-28", "closing": "480744.93", "opening": "505744.93", "deposits": "0.00", "withdrawals": "25000.00", "transactionCount": 2 }, { "date": "2025-01-29", "closing": "480744.93", "opening": "480744.93", "deposits": "0.00", "withdrawals": "0.00", "transactionCount": 0 }, { "date": "2025-01-30", "closing": "480744.93", "opening": "480744.93", "deposits": "0.00", "withdrawals": "0.00", "transactionCount": 0 }, { "date": "2025-01-31", "closing": "395000.00", "opening": "480744.93", "deposits": "0.00", "withdrawals": "85744.93", "transactionCount": 1 } ], "transactions": [ { "date": "2025-01-01", "description": "Wire In - Progress Billing", "amount": "128986.06", "lineOrder": 0 }, { "date": "2025-01-01", "description": "Wire Out - Subcontractor", "amount": "-53397.67", "lineOrder": 1 }, { "date": "2025-01-01", "description": "ACH Debit - Rent", "amount": "-18361.71", "lineOrder": 2 }, { "date": "2025-01-02", "description": "Business Debit Card - Supplies", "amount": "-13945.05", "lineOrder": 3 }, { "date": "2025-01-03", "description": "ACH Debit - Equipment Lease", "amount": "-12077.35", "lineOrder": 4 }, { "date": "2025-01-04", "description": "Check #4002 - Materials", "amount": "-4048.81", "lineOrder": 5 }, { "date": "2025-01-06", "description": "Business Debit Card - Fuel", "amount": "-1609.23", "lineOrder": 6 }, { "date": "2025-01-08", "description": "ACH Credit - Client Payment", "amount": "56744.55", "lineOrder": 7 }, { "date": "2025-01-08", "description": "Wire Out - Subcontractor", "amount": "-45868.48", "lineOrder": 8 }, { "date": "2025-01-09", "description": "ACH Debit - Supplier", "amount": "-7598.16", "lineOrder": 9 }, { "date": "2025-01-10", "description": "Business Debit Card - Supplies", "amount": "-18081.51", "lineOrder": 10 }, { "date": "2025-01-10", "description": "ACH Debit - Insurance", "amount": "-7622.74", "lineOrder": 11 }, { "date": "2025-01-12", "description": "Business Debit Card - Supplies", "amount": "-8877.54", "lineOrder": 12 }, { "date": "2025-01-13", "description": "ACH Debit - Supplier", "amount": "-11333.46", "lineOrder": 13 }, { "date": "2025-01-15", "description": "ACH Debit - Payroll", "amount": "-95548.05", "lineOrder": 14 }, { "date": "2025-01-17", "description": "Business Debit Card - Fuel", "amount": "-1642.13", "lineOrder": 15 }, { "date": "2025-01-19", "description": "ACH Debit - Subcontractor", "amount": "-59518.68", "lineOrder": 16 }, { "date": "2025-01-20", "description": "ACH Debit - Utilities", "amount": "-2227.49", "lineOrder": 17 }, { "date": "2025-01-22", "description": "Wire In - Progress Billing", "amount": "128880.13", "lineOrder": 18 }, { "date": "2025-01-23", "description": "ACH Debit - Subcontractor", "amount": "-27124.23", "lineOrder": 19 }, { "date": "2025-01-25", "description": "Wire In - Progress Billing", "amount": "250389.26", "lineOrder": 20 }, { "date": "2025-01-25", "description": "Check #4001 - Materials", "amount": "-4657.47", "lineOrder": 21 }, { "date": "2025-01-26", "description": "ACH Debit - Supplier", "amount": "-50715.31", "lineOrder": 22 }, { "date": "2025-01-28", "description": "Wire Out - Partner Distribution (Chen)", "amount": "-12500.00", "lineOrder": 23 }, { "date": "2025-01-28", "description": "Wire Out - Partner Distribution (Whitmore)", "amount": "-12500.00", "lineOrder": 24 }, { "date": "2025-01-31", "description": "ACH Debit - Payroll", "amount": "-85744.93", "lineOrder": 25 } ], "document_type": "bank_statement" } } ] } ``` **SDK Code** ```python import requests url = "https://api.spreadspace.app/api/borrowers/3f9c2b1e8d7a4c5b9e0f1a2b/extractions/bank-statements" headers = {"Authorization": "Bearer "} response = requests.get(url, headers=headers) print(response.json()) ``` ```javascript const url = 'https://api.spreadspace.app/api/borrowers/3f9c2b1e8d7a4c5b9e0f1a2b/extractions/bank-statements'; const options = {method: 'GET', headers: {Authorization: 'Bearer '}}; try { const response = await fetch(url, options); const data = await response.json(); console.log(data); } catch (error) { console.error(error); } ``` ```go package main import ( "fmt" "net/http" "io" ) func main() { url := "https://api.spreadspace.app/api/borrowers/3f9c2b1e8d7a4c5b9e0f1a2b/extractions/bank-statements" req, _ := http.NewRequest("GET", url, nil) req.Header.Add("Authorization", "Bearer ") res, _ := http.DefaultClient.Do(req) defer res.Body.Close() body, _ := io.ReadAll(res.Body) fmt.Println(res) fmt.Println(string(body)) } ``` ```ruby require 'uri' require 'net/http' url = URI("https://api.spreadspace.app/api/borrowers/3f9c2b1e8d7a4c5b9e0f1a2b/extractions/bank-statements") http = Net::HTTP.new(url.host, url.port) http.use_ssl = true request = Net::HTTP::Get.new(url) request["Authorization"] = 'Bearer ' response = http.request(request) puts response.read_body ``` ```java import com.mashape.unirest.http.HttpResponse; import com.mashape.unirest.http.Unirest; HttpResponse response = Unirest.get("https://api.spreadspace.app/api/borrowers/3f9c2b1e8d7a4c5b9e0f1a2b/extractions/bank-statements") .header("Authorization", "Bearer ") .asString(); ``` ```php request('GET', 'https://api.spreadspace.app/api/borrowers/3f9c2b1e8d7a4c5b9e0f1a2b/extractions/bank-statements', [ 'headers' => [ 'Authorization' => 'Bearer ', ], ]); echo $response->getBody(); ``` ```csharp using RestSharp; var client = new RestClient("https://api.spreadspace.app/api/borrowers/3f9c2b1e8d7a4c5b9e0f1a2b/extractions/bank-statements"); var request = new RestRequest(Method.GET); request.AddHeader("Authorization", "Bearer "); IRestResponse response = client.Execute(request); ``` ```swift import Foundation let headers = ["Authorization": "Bearer "] let request = NSMutableURLRequest(url: NSURL(string: "https://api.spreadspace.app/api/borrowers/3f9c2b1e8d7a4c5b9e0f1a2b/extractions/bank-statements")! as URL, cachePolicy: .useProtocolCachePolicy, timeoutInterval: 10.0) request.httpMethod = "GET" request.allHTTPHeaderFields = headers let session = URLSession.shared let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in if (error != nil) { print(error as Any) } else { let httpResponse = response as? HTTPURLResponse print(httpResponse) } }) dataTask.resume() ```