> 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.
# The Investment Income Statement object
> The extracted net investment income table: its lines, headline figures and checks as the readers return them.
An extracted net investment income table.
The retrieve endpoint returns this object on its own. The list endpoint
returns one per document, wrapped as
`{ "borrower_id": …, "statements": [ { "extracted_document_id", "document_category", "report_data" } ] }`.
## Explore
[Retrieve an investment income statement](/api/api-reference/investment-income-statements/get-investment-income-statement)
GET`/api/borrowers/:borrower_id/extractions/:doc_id/investment-income-statement`
[List all investment income statements](/api/api-reference/investment-income-statements/get-investment-income-statements)
GET`/api/borrowers/:borrower_id/extractions/investment-income-statements`
`lines` carries the table's printed rows in order, each with one figure
and one print mark per column, and `gross_investment_income`,
`investment_expenses` and `net_investment_income` carry the headline
rows the same way. `status` and `signals` say whether the table adds up.
The documents behind this object carry `document_category` `investment_income_statement`, `net_investment_income`, `net_investment_income_statement`, `investment_income` or `investment-income-statement`. Money keys are JSON strings with exactly two decimals (`"9200000.00"`, `"-1250.50"`). Date keys are `YYYY-MM-DD`, as each key's Type column shows.
## Fields
| Key | Type | Present when | Description |
| --------------------------------- | ---------------------------------------------------------- | ------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `entity` | string, nullable | Always | The reporting entity's name as printed, when the page prints one. |
| `title` | string, nullable | Always | The table's printed title. |
| `period` | string, nullable | Always | The period wording printed over the table, such as the years ended, when it prints one. |
| `periods` | array of objects | Always | The table's figure columns, one entry per column. |
| `columns` | integer | Always | Number of figure columns. |
| `lines` | array of objects | Always | The table's printed lines from the first component through net investment income, in print order. |
| `net_investment_income` | array of string (money) or null | Always | Net investment income per column. |
| `investment_expenses` | array of string (money) or null, nullable | Always | Investment expenses per column, as a negative figure; null in a column where the table prints none. |
| `gross_investment_income` | array of string (money) or null, nullable | Always | Gross investment income per column; null when the table prints no gross investment income line. |
| `net_investment_income_printed` | array of string, one of `money`, `dash`, `blank` | Always | How each figure of `net_investment_income` is printed, per column: `money`, `dash` for a printed dash, `blank` for an empty cell. |
| `investment_expenses_printed` | array of string, one of `money`, `dash`, `blank` | Always | How the investment expenses are printed, per column: `dash` when every expense cell in the column prints a dash, `blank` when the column prints none, `money` otherwise. |
| `gross_investment_income_printed` | array of string, one of `money`, `dash`, `blank`, nullable | Always | How each figure of `gross_investment_income` is printed, per column; null when the table prints no gross investment income line. |
| `cpa_engagement` | integer | On a statement extracted with its assurance level and presentation read; absent on an older extraction. | The accountant's level of assurance: 0 unaudited, 1 compiled, 2 reviewed, 3 audited. |
| `cpa_engagement_label` | string | On a statement extracted with its assurance level and presentation read; absent on an older extraction. | The assurance level in words. |
| `presentation` | string, one of `formal`, `free_form` | On a statement extracted with its assurance level and presentation read; absent on an older extraction. | 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). |
| `status` | string, one of `RECONCILED`, `FLAGGED` | Always | `RECONCILED` when the components less the investment expenses reach the printed net investment income and a printed gross investment income line equals the components above it, in every column; `FLAGGED` otherwise. |
| `signals` | array of objects | When the document states it | Each check of the table that does not hold, in words, when any does not. |
| `reporting_unit` | string, one of `ones`, `thousands`, `millions`, `billions` | Always | The unit the figures are printed in, such as ones or thousands. |
| `scale_multiplier` | integer | Always | Scale of the printed figures: 1 for whole dollars, 1000 when the table is stated in thousands, 1000000 when it is stated in millions. |
| `billing_years` | integer | Always | Years of data billed for the table. |
| `packet` | object | When the document states it | Where the table sat in the financial statement packet it arrived in, when it arrived in one. |
## `periods[]`
One figure column.
| Key | Type | Present when | Description |
| ---------- | ----------------------------- | ------------ | -------------------------------------------------------------------------------------------- |
| `label` | string, nullable | Always | The column heading as printed. |
| `coverage` | string, nullable | Always | The span the column covers as printed, such as a year ended date, when the table prints one. |
| `start` | string (YYYY-MM-DD), nullable | Always | First day of the period the column covers, when it can be dated. |
| `end` | string (YYYY-MM-DD), nullable | Always | Last day of the period the column covers, when it can be dated. |
## `lines[]`
One printed line.
| Key | Type | Present when | Description |
| --------- | ---------------------------------------------------------------------------- | ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `label` | string | Always | The line's caption as printed; empty on an unlabelled subtotal. |
| `kind` | string, one of `component`, `expense`, `gross`, `net`, `subtotal`, `caption` | Always | `component` for an investment income component, `expense` for an investment expense, `gross` for gross investment income, `net` for net investment income, `subtotal` for a line that prints the running total of the lines above it, `caption` for a heading that prints no figures. |
| `values` | array of string (money) or null | Always | The line's figure per column; null where the cell is blank. |
| `printed` | array of string, one of `money`, `dash`, `blank` | Always | How each cell is printed, per column: `money`, `dash` for a printed dash, `blank` for an empty cell. |
## `signals[]`
A check of the table that does not hold, or a note about its reporting period.
| Key | Type | Present when | Description |
| ---------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------ | ----------------------------------------------- |
| `severity` | string, one of `info`, `warn` | Always | How much weight the note carries: info or warn. |
| `code` | string, one of `coverage_unreadable`, `nii_gross_identity_mismatch`, `nii_net_identity_mismatch`, `no_reporting_period`, `year_from_file_metadata`, `year_from_filename`, `year_from_page_image`, `year_matches_print_stamp` | Always | The note's identifier. |
| `detail` | string | Always | The note in words. |
## `packet`
Where the table sat in the financial statement packet it arrived in, when it arrived in one.
| Key | Type | Present when | Description |
| --------------- | ----------------------------- | ------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------ |
| `section_index` | integer | Always | Position of the statement among the packet's statements, counting from zero. |
| `pages` | array of integer | Always | First and last page of the statement within the packet, counting from one. |
| `letter_date` | string (YYYY-MM-DD), nullable | Always | Date of the accountant's letter that accompanied the packet, when the letter printed one. |
| `letter_page` | integer, nullable | Always | Page of the packet the accountant's letter is on, when the packet carries one. |
| `page_list` | array of integer | On a statement whose pages in the packet are not one unbroken run; absent otherwise. | Every page of the packet the statement is printed on, counting from one, when they are not one unbroken run; absent otherwise. |