> For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://docs.spreadspace.app/api/api-reference/comprehensive-income-statements/get-comprehensive-income-statements/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.spreadspace.app/_mcp/server. # List all comprehensive income statements GET https://api.spreadspace.app/api/borrowers/{borrower_id}/extractions/comprehensive-income-statements Lists every usable comprehensive income 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/comprehensive-income-statements/get-comprehensive-income-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-07-19`. 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 ComprehensiveIncomeStatementReportDataListItem, 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 ### ComprehensiveIncomeStatementReportDataListItem One row of the Comprehensive Income Statement list: the document's identity and its extracted object. - `extracted_document_id` (string, required) — Identifier of the extracted document. - `document_category` (string, required) — The document category the extraction is stored under. - `report_data` (ComprehensiveIncomeStatementReportData, 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. ### ComprehensiveIncomeStatementReportData A statement of comprehensive income: net income, the other comprehensive income items, their total, comprehensive income and its split between the company and the noncontrolling interests, with one figure per period. Figures are decimal strings with two decimals, in dollars. - `entity` (string, required, nullable) — The reporting entity's name as printed. - `title` (string, required, nullable) — The statement's printed title. - `period` (string, required, nullable) — The period wording printed over the statement, such as the years ended, when it prints one. - `periods` (list of ComprehensiveIncomeStatementReportData_ComprehensiveIncomePeriod, required) — The statement's figure columns, one entry per column. - `columns` (integer, required) — Number of figure columns. - `lines` (list of ComprehensiveIncomeStatementReportData_ComprehensiveIncomeLine, required) — The statement's printed lines from net income through comprehensive income and its split, in print order. - `net_income` (list of string, required) — Net income per column. - `total_other_comprehensive_income` (list of string, required) — Total other comprehensive income per column: the printed total, or the total of the items when the statement prints none. - `comprehensive_income` (list of string, required) — Comprehensive income per column. - `comprehensive_income_attributable_to_parent` (list of string, required, nullable) — Comprehensive income attributable to the company per column; null when the statement prints no such line. - `comprehensive_income_attributable_to_noncontrolling` (list of string, required, nullable) — Comprehensive income attributable to the noncontrolling interests per column; null when the statement prints no such line. - `net_income_printed` (list of enum, required) — How each figure of `net_income` is printed, per column: `money`, `dash` for a printed dash, `blank` for an empty cell. - Allowed values: `money`, `dash`, `blank` - `total_other_comprehensive_income_printed` (list of enum, required) — How each figure of `total_other_comprehensive_income` is printed, per column. - Allowed values: `money`, `dash`, `blank` - `comprehensive_income_printed` (list of enum, required) — How each figure of `comprehensive_income` is printed, per column. - Allowed values: `money`, `dash`, `blank` - `comprehensive_income_attributable_to_parent_printed` (list of enum, required, nullable) — How each figure of the company's share is printed, per column; null when the statement prints no such line. - Allowed values: `money`, `dash`, `blank` - `comprehensive_income_attributable_to_noncontrolling_printed` (list of enum, required, nullable) — How each figure of the noncontrolling interests' share is printed, per column; null when the statement prints no such line. - Allowed values: `money`, `dash`, `blank` - `total_other_comprehensive_income_derived` (boolean, required) — True when the statement prints no total of other comprehensive income and `total_other_comprehensive_income` is the total of its items. - `nci_direction` (enum, required) — Whether the noncontrolling interests' line is deducted from (`subtract`) or added to (`add`) comprehensive income to reach the company's share, as the statement prints its sign; null when the statement prints no split. - Allowed values: `subtract`, `add` - `status` (enum, required) — `RECONCILED` when net income plus other comprehensive income equals comprehensive income, the items add to the printed total and the split nets to the company's share in every column; `FLAGGED` otherwise. - Allowed values: `RECONCILED`, `FLAGGED` - `reporting_unit` (enum, required) — The unit the figures are printed in, such as ones or thousands. - Allowed values: `ones`, `thousands`, `millions`, `billions` - `scale_multiplier` (integer, required) — Scale of the printed figures: 1 for whole dollars, 1000 when the statement is stated in thousands, 1000000 when it is stated in millions. - `billing_years` (integer, required) — Years of data billed for the statement. - `cpa_engagement` (integer, optional) — The accountant's level of assurance: 0 unaudited, 1 compiled, 2 reviewed, 3 audited. - `cpa_engagement_label` (string, optional) — The assurance level in words. - `presentation` (enum, optional) — How the statement is presented: `formal` when it is presented as issued financial statements; `free_form` when it is a report out of the books (accounting software or a spreadsheet). - Allowed values: `formal`, `free_form` - `signals` (list of ComprehensiveIncomeStatementReportData_StatementSignal, optional) — Each check of the statement that does not hold, in words, when any does not. - `packet` (ComprehensiveIncomeStatementReportData_PacketProvenance, optional) — Where the statement sat in the financial statement packet it arrived in, when it arrived in one. ### ComprehensiveIncomeStatementReportData_ComprehensiveIncomePeriod One figure column. - `label` (string, required, nullable) — The column heading as printed. - `coverage` (string, required, nullable) — The span the column covers as printed, such as a year ended date, when the statement prints one. - `start` (string, required, nullable) — First day of the period the column covers, when it can be dated. - `end` (string, required, nullable) — Last day of the period the column covers, when it can be dated. ### ComprehensiveIncomeStatementReportData_ComprehensiveIncomeLine One printed line. - `label` (string, required) — The line's caption as printed. - `kind` (enum, required) — `net` for net income, `ni_adjust` for a line that adjusts net income before the items (a preferred dividend, the noncontrolling interests' share of net income), `caption` for a heading that prints no figures, `item` for an other comprehensive income item, `subtotal` for a subtotal of items, `total_oci` for total other comprehensive income, `ci` for comprehensive income, `nci` for the noncontrolling interests' share of comprehensive income, `ci_parent` for the company's share. - Allowed values: `net`, `ni_adjust`, `caption`, `item`, `subtotal`, `total_oci`, `ci`, `nci`, `ci_parent` - `values` (list of string, required) — The line's figure per column; null where the cell is blank. - `printed` (list of enum, required) — How each cell is printed, per column: `money`, `dash` for a printed dash, `blank` for an empty cell. - Allowed values: `money`, `dash`, `blank` ### ComprehensiveIncomeStatementReportData_StatementSignal A check of the statement that does not hold, or a note about its reporting period. - `severity` (enum, required) — How much weight the note carries: info or warn. - Allowed values: `info`, `warn` - `code` (enum, required) — The note's identifier. - Allowed values: `coverage_unreadable`, `no_reporting_period`, `oci_ci_identity_mismatch`, `oci_nci_identity_mismatch`, `oci_total_identity_mismatch`, `year_from_file_metadata`, `year_from_filename`, `year_from_page_image`, `year_matches_print_stamp` - `detail` (string, required) — The note in words. ### ComprehensiveIncomeStatementReportData_PacketProvenance Where a statement sat in the financial statement packet it arrived in, when it arrived in one. - `section_index` (integer, required) — Position of the statement among the packet's statements, counting from zero. - `pages` (list of integer, required) — First and last page of the statement within the packet, counting from one. - `letter_date` (string, required, nullable) — Date of the accountant's letter that accompanied the packet, when the letter printed one. - `letter_page` (integer, required, nullable) — Page of the packet the accountant's letter is on, when the packet carries one. - `page_list` (list of integer, optional) — Every page of the packet the statement is printed on, counting from one, when they are not one unbroken run; absent otherwise. ## Examples **Response** ```json { "borrower_id": "3f9c2b1e8d7a4c5b9e0f1a2b", "statements": [ { "extracted_document_id": "7a1d4e9c2b3f4a5d8e6c1b0f", "document_category": "comprehensive_income_statement", "report_data": { "entity": "LANTERNFIELD TOOLS, INC.", "title": "Consolidated Statements of Comprehensive Income", "period": "Year Ended December 31", "periods": [ { "label": "2024", "coverage": "Year Ended December 31", "start": "2024-01-01", "end": "2024-12-31" }, { "label": "2023", "coverage": "Year Ended December 31", "start": "2023-01-01", "end": "2023-12-31" }, { "label": "2022", "coverage": "Year Ended December 31", "start": "2022-01-01", "end": "2022-12-31" } ], "columns": 3, "lines": [ { "label": "Net income", "kind": "net", "values": [ "52400000.00", "44100000.00", "37300000.00" ], "printed": [ "money", "money", "money" ] }, { "label": "Other comprehensive income (loss), net of tax", "kind": "caption", "values": [ null, null, null ], "printed": [ "blank", "blank", "blank" ] }, { "label": "Foreign currency translation adjustments", "kind": "item", "values": [ "-3200000.00", "1473000.00", "-2600000.00" ], "printed": [ "money", "money", "money" ] }, { "label": "Unrealized gains (losses) on cash flow hedges", "kind": "item", "values": [ "800000.00", "-2100000.00", "350000.00" ], "printed": [ "money", "money", "money" ] }, { "label": "Pension and postretirement plan adjustments", "kind": "item", "values": [ "1122000.00", "-1750000.00", "-900000.00" ], "printed": [ "money", "money", "money" ] }, { "label": "Total other comprehensive loss, net of tax", "kind": "total_oci", "values": [ "-1278000.00", "-2377000.00", "-3150000.00" ], "printed": [ "money", "money", "money" ] }, { "label": "Comprehensive income", "kind": "ci", "values": [ "51122000.00", "41723000.00", "34150000.00" ], "printed": [ "money", "money", "money" ] } ], "net_income": [ "52400000.00", "44100000.00", "37300000.00" ], "total_other_comprehensive_income": [ "-1278000.00", "-2377000.00", "-3150000.00" ], "comprehensive_income": [ "51122000.00", "41723000.00", "34150000.00" ], "comprehensive_income_attributable_to_parent": null, "comprehensive_income_attributable_to_noncontrolling": null, "net_income_printed": [ "money", "money", "money" ], "total_other_comprehensive_income_printed": [ "money", "money", "money" ], "comprehensive_income_printed": [ "money", "money", "money" ], "comprehensive_income_attributable_to_parent_printed": null, "comprehensive_income_attributable_to_noncontrolling_printed": null, "total_other_comprehensive_income_derived": false, "nci_direction": null, "status": "RECONCILED", "reporting_unit": "thousands", "scale_multiplier": 1000, "billing_years": 3 } } ] } ``` **SDK Code** ```python import requests url = "https://api.spreadspace.app/api/borrowers/3f9c2b1e8d7a4c5b9e0f1a2b/extractions/comprehensive-income-statements" headers = {"Authorization": "Bearer "} response = requests.get(url, headers=headers) print(response.json()) ``` ```javascript const url = 'https://api.spreadspace.app/api/borrowers/3f9c2b1e8d7a4c5b9e0f1a2b/extractions/comprehensive-income-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/comprehensive-income-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/comprehensive-income-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/comprehensive-income-statements") .header("Authorization", "Bearer ") .asString(); ``` ```php request('GET', 'https://api.spreadspace.app/api/borrowers/3f9c2b1e8d7a4c5b9e0f1a2b/extractions/comprehensive-income-statements', [ 'headers' => [ 'Authorization' => 'Bearer ', ], ]); echo $response->getBody(); ``` ```csharp using RestSharp; var client = new RestClient("https://api.spreadspace.app/api/borrowers/3f9c2b1e8d7a4c5b9e0f1a2b/extractions/comprehensive-income-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/comprehensive-income-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() ```