> 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 Profit Loss Statement object
> The extracted profit and loss statement record: revenue through net income as the readers return it.
An extracted profit loss statement.
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 a profit loss statement](/api/api-reference/profit-loss-statements/get-profit-loss-statement)
GET`/api/borrowers/:borrower_id/extractions/:doc_id/profit-loss-statement`
[List all profit loss statements](/api/api-reference/profit-loss-statements/get-profit-loss-statements)
GET`/api/borrowers/:borrower_id/extractions/profit-loss-statements`
`lines` carries the statement's rows in print order, each with its `label`, a
`depth` reflecting the document's own indentation and per-column `values`;
`period` and `periods` state the reporting period or periods. `cpa_engagement`
states the engagement level the statement was prepared under (`0` none, `1`
compiled or prepared, `2` reviewed, `3` audited), with `cpa_engagement_label`
as its display string.
The documents behind this object carry `document_category` `profit_and_loss`, `pl_statement`, `pl_statement_platform`, `income_statement`, `profit_and_loss_single`, `profit_and_loss_dual` or `profit_and_loss_multi`. 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 |
| ---------------------- | ---------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `document_type` | always `profit_loss_statement` | Always | Which family of document this is. |
| `entity` | string, nullable | Always | The reporting entity's name as printed. |
| `entity_source` | string | When the document states it | What names the entity when the statement's own page does not: the page image (`page_image`), the filing's cover page (`filing_cover`), or the opening pages of the financial statement packet the statement arrived in (`packet_text`); absent when the statement's own page names it. |
| `entity_source_sheet` | string | On a spreadsheet upload whose own sheet does not name the company, when the workbook names exactly one company; absent otherwise. | The sheet of the uploaded workbook that names the company, when this statement's own sheet does not and the workbook names exactly one company; absent otherwise. |
| `title` | string, nullable | Always | The statement's printed title. |
| `period` | string, nullable | Always | The reporting period as printed in the heading. |
| `period_source` | string, nullable | Always | Which part of the document states the reporting period: the printed heading (`printed`), the date the statement was printed on (`print_stamp`), a year the heading prints alone (`year_only`, the period being that year's end), the page image (`page_image`), the file's name (`filename`) or the file's own creation date (`file_metadata`); null when none of these dates the statement. |
| `periods` | array of objects | Always | The statement's figure columns, one entry per column. |
| `billing_years` | integer | Always | Years of data billed: the distinct years among columns that print a non-zero figure; 0 when no column prints one (such a document is not billed). |
| `columns` | integer | Always | Number of figure columns. |
| `reporting_unit` | string, one of `ones`, `thousands`, `millions`, `billions` | On a profit and loss, balance sheet or cash flow statement; absent on an older extraction. | The unit the figures are printed in; on the wire the figures are already whole dollars. |
| `scale_multiplier` | integer | On a profit and loss, balance sheet or cash flow statement; absent on an older extraction. | Scale of the printed figures: 1 for whole dollars, 1000 when the statement is stated in thousands, 1000000 when it is stated in millions, 1000000000 when it is stated in billions. |
| `unit_exceptions` | array of string | On a profit and loss, balance sheet or cash flow statement; absent on an older extraction. | The carve-outs the statement's unit declaration lists, such as per share amounts, whose lines and columns keep their printed figures; empty when it lists none. |
| `unit_source` | string, one of `printed`, `none` | On a profit and loss, balance sheet or cash flow statement; absent on an older extraction. | Where the statement states its unit: `printed` when the statement header, a column header or a heading line prints it; `none` when nothing is printed and the figures are whole dollars as printed. |
| `lines` | array of objects | Always | The printed lines in order. |
| `component_columns` | array of objects | On a statement that prints component columns beside a total; absent otherwise. | The columns the statement prints beside a total as its parts, such as one per class or location, when it prints any. |
| `entity_split` | object | On a statement read out of a page whose columns are separate companies; absent otherwise. | Which part of a page whose columns are separate companies this statement is; absent on every other statement. |
| `canonical` | object | When the document states it | The printed lines mapped onto standard line names. |
| `per_share` | object | On a profit and loss whose statement prints a per-share block under the bottom line (earnings per share, weighted-average shares); absent otherwise. | The per-share block printed under the bottom line, when the statement prints one: earnings per share and weighted-average shares, basic and diluted, one row each as printed. |
| `supplemental` | object | On a profit and loss whose statement prints rows under the bottom line besides a per-share block; absent otherwise. | The rows printed under the bottom line besides the per-share block, when the statement prints any: other comprehensive income, a retained earnings roll-forward, supplemental lines. |
| `cpa_engagement` | integer | When the document states it | The accountant's level of assurance: 0 unaudited, 1 compiled, 2 reviewed, 3 audited. |
| `cpa_engagement_label` | string | When the document states it | The assurance level in words. |
| `presentation` | string, one of `formal`, `free_form` | On a profit and loss, balance sheet or cash flow statement (a spreadsheet upload reads free_form); absent on an older extraction. | How the statement is presented: `formal` when it is presented as issued financial statements (a CPA engagement stated, a reference to the notes to the financial statements, a per-share block, the supplemental cash flow disclosures, the preparation legend that no assurance is provided, a plural statement title such as balance sheets or statements of income, or a statement of changes in equity or plural statement titles in the packet it arrived in); `free_form` when it is a report out of the books (accounting software or a spreadsheet). |
| `signals` | array of objects | When the document states it | Notes about the statement's reporting period, when any. |
| `packet` | object | When the document states it | Where the statement sat in the financial statement packet it arrived in, when it arrived in one. |
| `summary` | object | On the single-document read, when at least one summary row matches a printed line; not on the list or the untyped reads. | The statement's headline figures, on the single-document read. |
## `periods[]`
One figure column.
| Key | Type | Present when | Description |
| ----------------------- | ----------------------------- | --------------------------- | --------------------------------------------------------------------------- |
| `label` | string, nullable | Always | The column header as printed. |
| `coverage` | string, nullable | Always | The span of time the column covers. |
| `start` | string (YYYY-MM-DD), nullable | When the document states it | First day of the period, when the header states one. |
| `end` | string (YYYY-MM-DD), nullable | When the document states it | Last day of the period, when the header states one. |
| `rollup` | boolean | When the document states it | True when the column totals the other columns. |
| `consolidating_columns` | integer | When the document states it | On a consolidating statement, the number of entity columns the total spans. |
## `lines[]`
One printed line.
| Key | Type | Present when | Description |
| ------------------ | ------------------------------- | ------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------- |
| `label` | string | Always | The line's label as printed. |
| `depth` | integer | Always | Indentation level of the line, counting from zero. |
| `values` | array of string (money) or null | Always | The line's figure per column; null where the column is blank. |
| `component_values` | array of string (money) or null | On a statement that prints component columns beside a total; absent otherwise. | The line's figure in each component column, in the order of component_columns; null where the column is blank. |
## `component_columns[]`
One column printed as a part of a total column.
| Key | Type | Present when | Description |
| -------------- | ---------------- | --------------------------- | ---------------------------------------------------------------------------------------------------------- |
| `label` | string, nullable | Always | The column header as printed; null when the column prints none. |
| `total_column` | integer | Always | Position among the statement's period columns of the total the component is a part of, counting from zero. |
| `after_total` | boolean | When the document states it | True when the column is printed to the right of its total; absent otherwise. |
## `entity_split`
Which part of a page whose columns are separate companies this statement is; absent on every other statement.
| Key | Type | Present when | Description |
| --------- | -------------------------------- | --------------------------- | ---------------------------------------------------------------------------------------------------------- |
| `role` | string, one of `total`, `member` | Always | `total` on the statement of the page's total column, `member` on the statement of one company's column. |
| `members` | array of string | When the document states it | On the total's statement, the names of the companies whose columns the page prints. |
| `total` | string, nullable | When the document states it | On a member's statement, the entity the page's total column is for, or null when the page prints no total. |
## `canonical`
The printed lines mapped onto standard line names.
| Key | Type | Present when | Description |
| ---------------- | ---------------- | ------------ | --------------------------------------------------------------------------------- |
| `schema_version` | string, nullable | Always | Version of the standard line vocabulary the names come from. |
| `statement` | string | Always | Which statement vocabulary applies: balance_sheet, income_statement or cash_flow. |
| `rows` | array of objects | Always | One entry per printed line, in print order. |
| `blocks` | array of objects | Always | One entry per printed subtotal and the lines that foot into it. |
| `gates` | object | Always | Summary verdicts over the whole statement. |
| `entity_signal` | string, nullable | Always | A note about the entity the statement belongs to, when the line names carry one. |
### `canonical.rows[]`
One printed line and the standard line name it corresponds to.
| Key | Type | Present when | Description |
| ------------------- | ---------------------------------------------------------------------- | ------------ | ---------------------------------------------------------------------------------------------------------------------- |
| `key` | string | Always | Address of the printed line within the statement. |
| `raw_label` | string, nullable | Always | The line's label as printed. |
| `concept_id` | string, nullable | Always | The standard line name the printed label corresponds to, or null when it corresponds to none. |
| `method` | string, one of `exact`, `fuzzy`, `keyword`, `structural`, `reconciled` | Always | How closely the printed label matches the standard name: exact, fuzzy, structural, or reconciled when it matches none. |
| `block` | string, nullable | Always | The subtotal block the line belongs to, when it belongs to one. |
| `parent_concept_id` | string, nullable | Always | The standard name of the subtotal the line foots into, when it foots into one. |
### `canonical.blocks[]`
A printed subtotal and whether its lines foot into it.
| Key | Type | Present when | Description |
| ------------------- | ---------------- | ------------ | -------------------------------------------------------------------------------- |
| `id` | string | Always | Address of the subtotal's printed line. |
| `parent_concept_id` | string, nullable | Always | The standard name of the subtotal, when it corresponds to one. |
| `footing` | string | Always | Whether the lines above the subtotal add up to it: pass, fail or not_applicable. |
### `canonical.gates`
Summary verdicts over the whole statement.
| Key | Type | Present when | Description |
| -------------------- | ------- | ------------ | ------------------------------------------------------------------------------------------------------- |
| `identity` | string | Always | Whether total assets equal total liabilities plus equity on every column: pass, fail or not_applicable. |
| `classified_footing` | string | Always | Whether the current and noncurrent subtotals foot: pass, fail or not_applicable. |
| `blocks_failed` | integer | Always | Number of printed subtotals whose lines do not add up to them. |
## `per_share`
The per-share block printed under the bottom line, when the statement prints one: earnings per share and weighted-average shares, basic and diluted, one row each as printed.
| Key | Type | Present when | Description |
| ------------ | ---------------- | ------------ | ----------------------------------------------------------------------------------------------------------- |
| `rows` | array of objects | Always | One row per printed per-share or share-count line, in print order. |
| `share_unit` | string | Always | The unit the share counts were printed in (ones, thousands, millions); the values are already whole shares. |
### `per_share.rows[]`
One per-share line as printed.
| Key | Type | Present when | Description |
| -------- | ------------------------------------------------------------ | ------------ | -------------------------------------------------------------------------------------------------------------------- |
| `kind` | string, one of `eps`, `shares` | Always | `eps` for a per-share figure (dollars per share to the cent, as printed), `shares` for a share count (whole shares). |
| `basis` | string, one of `basic`, `diluted`, `basic_and_diluted`, \`\` | Always | `basic`, `diluted`, `basic_and_diluted`, or empty when the line states neither. |
| `label` | string | Always | The line's printed caption. |
| `values` | array of string or null | Always | One value per figure column, as strings; null where the column prints none. |
## `supplemental`
The rows printed under the bottom line besides the per-share block, when the statement prints any: other comprehensive income, a retained earnings roll-forward, supplemental lines.
| Key | Type | Present when | Description |
| ------ | ---------------- | ------------ | ----------------------------------------- |
| `rows` | array of objects | Always | One row per printed line, in print order. |
### `supplemental.rows[]`
One line printed under the bottom line.
| Key | Type | Present when | Description |
| ----------- | ----------------------------------------------------------------------- | ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `kind` | string, one of `oci`, `retained_earnings`, `supplemental_info`, `other` | Always | What the line belongs to: `oci` for other comprehensive income, `retained_earnings` for a retained earnings or equity roll-forward, `supplemental_info` for a supplemental disclosure, `other` for any other line. |
| `label` | string | Always | The line's printed caption. |
| `is_header` | boolean | Always | True when the line heads the lines under it. |
| `values` | array of string (money) or null | Always | The line's figure per column; null where the column is blank. |
## `signals[]`
A note about the statement's 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`, `interest_netted_with_other`, `line_enters_against_its_name`, `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 statement 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. |
## `summary`
The statement's headline figures, on the single-document read.
| Key | Type | Present when | Description |
| ---------- | ---------------- | ------------ | ---------------------------------------- |
| `title` | string | Always | The period the rows cover, as a heading. |
| `sections` | array of objects | Always | The row blocks, in display order. |
### `summary.sections[]`
A block of headline rows under one heading.
| Key | Type | Present when | Description |
| --------- | ---------------- | ------------ | -------------------------------------------------------------- |
| `key` | string | Always | The block's identifier, for example assets, liabilities or pl. |
| `heading` | string, nullable | Always | The block's heading, or null when the block has none. |
| `rows` | array of objects | Always | The rows of the block, in display order. |
#### `summary.sections[].rows[]`
One headline figure and the printed line it names.
| Key | Type | Present when | Description |
| ------------ | ------------------------ | --------------------------- | --------------------------------------------------------------------------------------------------- |
| `key` | string | Always | The row's identifier, for example revenue, cogs or net_profit. |
| `label` | string | Always | The row's wording as displayed. |
| `value` | string (money), nullable | Always | The figure in dollars, or null when the printed line carries no figure. |
| `aggregated` | boolean | When the document states it | True when the figure combines more than one printed line rather than reading a single printed cell. |
| `emphasis` | boolean | When the document states it | True on a section total or a bottom line. |
| `depth` | integer | When the document states it | Indentation of the row beneath the row above it, counting from zero. |
| `pinned` | boolean | When the document states it | True on a row that stays in view when its section is collapsed. |