> 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 Balance Sheet object
> The extracted balance sheet record: asset, liability, and equity lines as the balance sheet readers return them.
An extracted balance sheet.
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 balance sheet](/api/api-reference/balance-sheets/get-balance-sheet-statement)
GET`/api/borrowers/:borrower_id/extractions/:doc_id/balance-sheet-statement`
[List all balance sheets](/api/api-reference/balance-sheets/get-balance-sheets)
GET`/api/borrowers/:borrower_id/extractions/balance-sheets`
`balance_sheet` carries the statement's rows as a labeled tree in the
document's own grouping, `sections` the same content flattened by side, and
`periods` the statement's columns with their `as_of` dates. `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` `balance_sheet`, `balance_sheet_platform`, `balance_sheet_single`, `balance_sheet_dual`, `comparative_balance_sheet`, `balance_sheet_multi`, `monthly_balance_sheet`, `quarterly_balance_sheet` or `trend_balance_sheet`. Money keys are JSON strings with exactly two decimals (`"9200000.00"`, `"-1250.50"`). Date keys are as printed on the document unless a key's Type column states a format.
## Fields
| Key | Type | Present when | Description |
| ------------------------------ | ---------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `document_type` | always `balance_sheet` | Always | Which family of document this is. |
| `entity` | string, nullable | When the document states it | 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. |
| `periods` | array of objects | Always | The statement's columns, one entry per period, newest first. |
| `period_count` | integer | Always | Number of period columns. |
| `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). |
| `as_of_year` | integer, nullable | When the document states it | The year of the latest period, when the document states one. |
| `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. |
| `balance_sheet` | array of BalanceSheetRow | Always | The printed lines as a tree: section headings, their lines, and subtotals. |
| `receivable_allowances` | array of objects | On a balance sheet whose receivables caption states its allowance; absent otherwise. | The allowance each receivables line states in its own caption, when a caption states one. |
| `totals` | object | When the document states it | The headline totals per period, the totals the balance check used, and whether each of those is printed. |
| `total_assets` | string (money), nullable | Always | Total assets for the latest period. |
| `total_liabilities` | string (money), nullable | Always | Total liabilities for the latest period. |
| `total_mezzanine_equity` | string (money), nullable | When the document states it | Mezzanine equity for the latest period: the lines the statement prints between its liabilities and its equity, such as a redeemable noncontrolling interest or redeemable preferred stock, which are in neither total liabilities nor total equity. Null when the latest period prints none. |
| `total_equity` | string (money), nullable | Always | Total equity for the latest period. |
| `total_liabilities_and_equity` | string (money), nullable | Always | Total liabilities and equity for the latest period. |
| `sections` | array of objects | Always | The printed lines grouped by section, with subtotals marked. |
| `status` | string, one of `RECONCILED`, `FLAGGED` | Always | `RECONCILED` when total assets equal total liabilities and equity in every period; `FLAGGED` otherwise. |
| `signals` | array of objects | When the document states it | Notes about the statement's reporting period, when any. |
| `period_source` | string | When the document states it | Which part of the document dates the periods when the column headers state no date: the date the statement was printed on (`print_stamp`), a year a column 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`); absent when the column headers date the periods. |
| `canonical` | object | When the document states it | The printed lines mapped onto standard line names. |
| `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). |
| `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 by section, on the single-document read. |
## `periods[]`
One period column.
| Key | Type | Present when | Description |
| ---------- | ----------------------------- | ------------ | --------------------------------------------------------------- |
| `label` | string, nullable | Always | The column header as printed; null when the column prints none. |
| `as_of` | string (as printed), nullable | Always | The period's as-of date, when the header states one. |
| `inferred` | boolean | Always | True when the document prints no header for the period. |
## `receivable_allowances[]`
The allowance a receivables line states in its own caption.
| Key | Type | Present when | Description |
| ----------------- | ------------------------------- | ------------ | ---------------------------------------------------------------------------- |
| `label` | string | Always | The receivables line's label as printed. |
| `path` | string | Always | The receivables line's address in the tree. |
| `allowance_label` | string | Always | The allowance in words, for example Less allowance for credit losses. |
| `values` | array of string (money) or null | Always | The allowance per period; null where the caption states none for the period. |
## `totals`
The headline totals per period, the totals the balance check used, and whether each of those is printed.
| Key | Type | Present when | Description |
| ------------------------------ | ----------------------------------------- | --------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `TOTAL_ASSETS` | array of string (money) or null, nullable | When the document states it | Total assets per period as printed; null when the statement prints no such line. |
| `TOTAL_LIABILITIES` | array of string (money) or null, nullable | When the document states it | Total liabilities per period as printed; null when the statement prints no such line. |
| `TOTAL_MEZZANINE_EQUITY` | array of string (money) or null, nullable | When the document states it | Mezzanine equity per period as printed: the one line the statement prints between its liabilities and its equity, or the total it prints over several such lines; null when it prints several lines and no total over them. |
| `TOTAL_EQUITY` | array of string (money) or null, nullable | When the document states it | Total equity per period as printed; null when the statement prints no such line. |
| `TOTAL_LIABILITIES_AND_EQUITY` | array of string (money) or null, nullable | When the document states it | Total liabilities and equity per period as printed; null when the statement prints no such line. |
| `effective` | object | When the document states it | The totals the balance check used. |
| `src` | object | When the document states it | Whether each total the balance check used is printed. |
### `totals.effective`
The totals the balance check used.
| Key | Type | Present when | Description |
| ------------------------------ | ----------------------------------------- | --------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `TOTAL_ASSETS` | array of string (money) or null, nullable | When the document states it | Total assets per period used by the balance check: the printed total when the statement prints one, else the total its own figures give; null when neither exists. |
| `TOTAL_LIABILITIES` | array of string (money) or null, nullable | When the document states it | Total liabilities per period used by the balance check: the printed total when the statement prints one, else the total its own figures give; null when neither exists. |
| `TOTAL_MEZZANINE_EQUITY` | array of string (money) or null, nullable | When the document states it | Mezzanine equity per period used by the balance check: the printed figure when the statement prints one, else the total of the mezzanine lines it prints; null in a period that prints none. |
| `TOTAL_EQUITY` | array of string (money) or null, nullable | When the document states it | Total equity per period used by the balance check: the printed total when the statement prints one, else the total its own figures give; null when neither exists. |
| `TOTAL_LIABILITIES_AND_EQUITY` | array of string (money) or null, nullable | When the document states it | Total liabilities and equity per period used by the balance check: the printed total when the statement prints one, else the total its own figures give; null when neither exists. |
### `totals.src`
Whether each total the balance check used is printed.
| Key | Type | Present when | Description |
| ------------------------------ | ---------------- | --------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `TOTAL_ASSETS` | string, nullable | When the document states it | `printed` when the statement prints a total assets line, `derived` otherwise; null when the balance check had no such total. |
| `TOTAL_LIABILITIES` | string, nullable | When the document states it | `printed` when the statement prints a total liabilities line, `derived` otherwise; null when the balance check had no such total. |
| `TOTAL_MEZZANINE_EQUITY` | string, nullable | When the document states it | `printed` when the statement prints its mezzanine equity as one line or as a total over several lines, `derived` when it prints several lines and no total over them. |
| `TOTAL_EQUITY` | string, nullable | When the document states it | `printed` when the statement prints a total equity line, `derived` otherwise; null when the balance check had no such total. |
| `TOTAL_LIABILITIES_AND_EQUITY` | string, nullable | When the document states it | `printed` when the statement prints a total liabilities and equity line, `derived` otherwise; null when the balance check had no such total. |
## `sections[]`
One section of the statement.
| Key | Type | Present when | Description |
| ------- | ------------------------------------------------ | ------------ | ------------------------------------- |
| `name` | string | Always | The section heading as printed. |
| `side` | string, one of `assets`, `liabilities`, `equity` | Always | One of assets, liabilities or equity. |
| `items` | array of objects | Always | The section's lines in print order. |
### `sections[].items[]`
One line of a section.
| Key | Type | Present when | Description |
| ------------- | ------------------------ | ------------ | ----------------------------------------- |
| `label` | string | Always | The line's name. |
| `value` | string (money), nullable | Always | The line's figure for the latest period. |
| `is_subtotal` | boolean | Always | True when the line is a printed subtotal. |
## `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`, `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. |
## `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. |
## `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 by section, 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, cash or total_assets. |
| `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. |
## Shared objects
Object types that several keys above carry. The Type column names them.
### BalanceSheetRow
One printed line, with the lines nested under it when it heads a section.
| Key | Type | Present when | Description |
| ------------ | ----------------------------------------- | ------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------- |
| `label` | string | Always | The line's name: its printed label without the figures and detail the label states, which are in caption, footnote and components. |
| `values` | array of string (money) or null, nullable | Always | The line's figure per period; null where the column is blank, and null as a whole for a heading with no figures. |
| `path` | string | Always | The line's address in the tree. |
| `children` | array of BalanceSheetRow | Always | The lines nested under this one. |
| `caption` | string | On a line whose printed label says more than its name; absent otherwise. | The line's label exactly as printed, present when it states more than the name. |
| `footnote` | string | On a line whose printed label states detail beyond its name; absent otherwise. | What the printed label states beyond the line's name, such as a par value or share counts, as printed. |
| `components` | array of objects | On a line whose printed label states an amount it is net of; absent otherwise. | Present when the printed label states an amount the line is net of: the line before that deduction, then the deduction. |
#### `BalanceSheetRow.components[]`
One figure a net line's label states.
| Key | Type | Present when | Description |
| -------- | ----------------------------------- | ------------ | -------------------------------------------------------------------------------------------------------------------------------------------- |
| `role` | string, one of `gross`, `deduction` | Always | `gross` for the line before the deduction (the line's figure and the deduction added together), `deduction` for the amount the label states. |
| `label` | string | Always | The figure's name. |
| `values` | array of string (money) or null | Always | The figure per period; null where the label states none for the period. |