> 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 Mapping object

> A balance sheet placed on the chart of accounts, with the figure of every section and account per period, the printed lines behind each, and where each figure comes from in the document.

A balance sheet mapped onto the workspace's chart of accounts: each printed
line on its account, every section and account with its figure per period,
the headline measures, and the source of each figure in the document. A
mapping is prepared for every usable balance sheet after extraction;
[Statement mapping](/api/statement-mapping) is the guide to reading one, with
the arithmetic worked through. A profit and loss statement's mapping is its
own object,
[The Profit Loss Mapping object](/api/api-reference/statement-mappings/profit-loss-mapping).

The retrieve endpoint returns this object on its own. The list endpoint
returns one per document, wrapped as
`{ "data": [ … ], "limit", "next_cursor", "pending_document_ids" }`.

## Explore

[Retrieve a balance sheet mapping](/api/api-reference/statement-mappings/get-balance-sheet-mapping)

<path d="m9 18 6-6-6-6" />

GET`/api/borrowers/:borrower_id/extractions/:doc_id/balance-sheet-mapping`

[List all balance sheet mappings](/api/api-reference/statement-mappings/list-balance-sheet-mappings)

<path d="m9 18 6-6-6-6" />

GET`/api/borrowers/:borrower_id/extractions/balance-sheet-mappings`

## Attributes

* `mapping_id`: the mapping's id. A statement gets a new mapping, under a new
  id, when its extraction, the workspace's chart of accounts, caption rules or
  export map, or the mapping logic changes.
* `document_id`: the document the mapping is of.
* `status`: `ready` or `unmappable`. A ready mapping carries a `payload`, whose
  `mapping_state` says how far the statement could be mapped. `unmappable`
  means the statement could not be read as a balance sheet at all, and
  `payload` is null.
* `error_code`: `unmappable` on an unmappable mapping, otherwise null.
* `extraction_version`: the revision of the document's extraction the mapping
  was made from, the same `extraction_version` the document list and the
  document webhooks carry.
* `engine_version`: the version of the mapping logic that made the mapping.
* `chart_version`: the version of the platform chart of accounts the mapping's
  accounts come from. Null on an unmappable mapping.
* `chart_document_version`: the version of the workspace's chart of accounts
  the mapping was made under, the `version` that `GET /api/chart-of-accounts`
  returns. 0 when the workspace has saved no chart.
* `chart_rules_version`: the version of the workspace's caption rules the
  mapping was made under, the `rules_version` of the same read. 0 when none
  was written.
* `created_at`: when the mapping was made, RFC 3339 UTC.
* `stale`: true when the workspace's chart of accounts, caption rules or export
  map, or the mapping logic, changed after this mapping was made. A stale
  mapping is still returned while a new one is prepared; read again to receive
  it.
* `payload`: the mapping itself, described next. Null on an unmappable
  mapping.

Every figure in the payload is a decimal string with exactly two decimal
places, as the [value conventions](/api/conventions) state for money. Every
`values` and `sources` array, every measure and every entry of `foot` run in
the order of `periods`: position `i` of each belongs to period `i`.

### `payload`

* `schema_version`: the version of the payload's shape, 1.
* `statement`: the kind of statement. Always `balance_sheet`.
* `document_id`: the document the statement was extracted from.
* `mapping_state`: `mapped` when the statement's lines were placed on the chart
  of accounts and each side walks to the total the statement prints, so `tree`
  is present; `unfooted` when they could not be made to: `tree` is null,
  `lines` and `measures` state the statement as printed, and `foot` says by
  how much each period misses.
* `periods`: the statement's period columns, in the order every series of the
  mapping follows.
* `foot`: how the statement foots, one entry per period: the total assets and
  the total liabilities and equity it prints, the totals its lines walk to on
  each side, the difference between each pair, and the difference between the
  two sides.
* `export_system`: the export system whose codes the tree's accounts carry in
  `external_code`, the active system of `GET /api/chart-of-accounts/export-map`.
  Null when the workspace has no export map.
* `tree`: the statement on the chart of accounts, from current assets down to
  equity: sections, the accounts under them and measure rows such as total
  assets, each with its figure per period and the printed lines it holds. Every
  account in force is listed with its id, whether or not the statement has a
  figure for it. Null when `mapping_state` is `unfooted`.
* `lines`: every line the statement prints, in print order.
* `measures`: the statement's headline figures per period.
* `unmapped_lines`: the printed lines that carry a figure and that no account
  received. Empty when every line was placed.
* `unmapped_export_account_ids`: the account ids the workspace's export map
  gives a code that this mapping's tree does not list.
* `overrides_applied`: whether corrections made to the statement's figures in
  the workspace are reflected in the mapping. False.

### `payload.periods[]`

* `fiscal_year`: the fiscal year the period belongs to.
* `period_end`: the date the period ends, `YYYY-MM-DD`. Null when the statement
  does not state one.
* `label`: the period as the statement prints it. Null when it prints none.
* `months_covered`: how many months the period covers, 12 for a full year. Null
  when the printed period does not say.

### `payload.foot[]`

A statement prints rounded figures, so each side's lines may walk to a total a
few dollars from the one it prints. `tolerance` is how far apart the two may
be, and on a `mapped` statement each residual and the imbalance are within it.
On an `unfooted` statement a residual is the amount by which the printed lines
of that side miss the printed total.

* `printed_total_assets`: the total assets the statement prints for the period.
  Null when it prints none.
* `printed_total_assets_source`: where the printed total assets comes from, a
  source as described under [Sources](#sources). Null when the statement prints
  none.
* `assets_sum`: the total assets the statement's asset lines walk to. On a
  `mapped` statement it is the asset rows at the top of the tree, measures
  aside, each counted by its `effect`. Null when the lines give no such walk.
* `assets_residual`: `printed_total_assets` less `assets_sum`. `0.00` when the
  two agree. Null when either is null.
* `printed_total_liabilities_and_equity`: the total liabilities and equity the
  statement prints for the period. Null when it prints none.
* `printed_total_liabilities_and_equity_source`: where the printed total
  liabilities and equity comes from, a source as described under
  [Sources](#sources). Null when the statement prints none.
* `liabilities_and_equity_sum`: the total liabilities and equity the
  statement's liability and equity lines walk to. On a `mapped` statement it is
  the liability, mezzanine equity and equity rows at the top of the tree,
  measures aside, each counted by its `effect`. Null when the lines give no
  such walk.
* `liabilities_and_equity_residual`: `printed_total_liabilities_and_equity`
  less `liabilities_and_equity_sum`. `0.00` when the two agree. Null when
  either is null.
* `imbalance`: `assets_sum` less `liabilities_and_equity_sum`. `0.00` when the
  two sides balance. Null when either is null.
* `tolerance`: the difference the footing allows in the period, for the
  rounding of printed figures. A residual of `0.50` beside a tolerance of
  `1.00` is a side that foots. Null when the lines give no walk.

### Sources

Every figure on a tree node, on a printed line and on the foot states where it
comes from.

* `kind`: `printed` when the document prints the figure, at `address`.
  `derived` when the figure is arrived at from figures the document prints,
  such as a section total the statement does not print or a measure.
* `document_id`: the document the figure comes from. Null when the mapping
  records none for the figure.
* `address`: a printed figure's address in the document's report data, the
  printed line and the column the figure sits in, so the figure joins to the
  line the balance sheet read returns. Null when `kind` is `derived`.
* `pages`: the pages of the document the figure is printed on, numbered from
  1, in ascending order. A figure of kind `derived` lists the pages of the
  figures it comes from. Empty when the document records no page for the
  figure.

### `payload.tree[]`

One row of the mapped statement: a section or a grouping of accounts
(`folder`), an account (`leaf`), or a computed row such as total assets
(`measure`). Rows nest through `children`. The tree recomputes from the
payload, to the cent, by the rules on the
[Statement mapping](/api/statement-mapping#the-balance-sheets-arithmetic)
page.

* `kind`: `folder`, `leaf` or `measure`.
* `key`: the node's key, unique within the tree. An account's key is its
  account id, a section's is `bs.` followed by the section, and a measure's is
  `m:` followed by the measure's name.
* `label`: the node's name in the chart of accounts.
* `account_id`: the chart account's id, on a `leaf`. Null on a folder and on a
  measure.
* `section`: the statement section the node sits in: `current_assets`,
  `noncurrent_assets`, `current_liabilities`, `longterm_liabilities`,
  `mezzanine_equity` or `equity`. Null on a node that sits in no one section,
  such as a measure.
* `role`: on the folder that stands for a whole section, that section's name.
  Null on every other node.
* `measure`: on a `measure`, which one: `total_assets`, `total_liabilities`,
  `total_liabilities_and_equity` or `working_capital`. Null on every other
  node.
* `external_code` and `external_label`: the account's code and name in the
  workspace's export system, when its export map gives the account them. Null
  otherwise.
* `effect`: `adds` or `subtracts`, how the node's figures count toward its
  side's total: total assets on an asset node, total liabilities and equity on
  a liability, mezzanine equity or equity node. A positive figure on an `adds`
  node raises it, on a `subtracts` node lowers it; accumulated depreciation and
  distributions are `subtracts` nodes. Null on a measure.
* `values`: the node's figure per period, positive in the direction of
  `effect`. Null where it has none.
* `unitemized`: the part of each figure of `values` that the statement prints
  no line for: the figure, less the nodes under it, less the lines placed on
  it. `0.00` where they account for all of it. Null where the figure is null,
  and in every period on a measure.
* `sources`: where each figure of `values` comes from, in the same order. Null
  where the figure is null.
* `member_keys`: the keys of the printed lines the node holds, those of the
  nodes under it included. Each is the `key` of a member of `lines`.
* `direct_member_keys`: the keys of the printed lines placed on the node itself
  rather than on a node under it, in the statement's order.
* `flagged_keys`: the keys of the node's printed lines that are marked for a
  reader's attention. A marked line stays where it is placed. Empty when none
  is marked.
* `reclassified_keys`: always empty. The key stays so the shape of a node is
  unchanged.
* `children`: the nodes under this one. Empty when it has none.

### `payload.lines[]`

* `key`: the line's key, unique within the statement. The tree's `member_keys`
  and the mapping's `unmapped_lines` name lines by it.
* `label`: the line's caption as printed.
* `depth`: how far the line is indented on the statement, 0 for the outermost
  level.
* `is_total`: whether the line is a total or a subtotal of the lines above it.
* `values`: the line's figure per period, as the statement prints it, in the
  statement's own sign presentation: a contra line printed unsigned under a
  Less caption carries its printed figure, and one printed in parentheses
  carries a negative figure. Null where the statement prints none.
* `sources`: where each figure of `values` comes from, in the same order. Null
  where the figure is null.
* `filed_under`: the key of the tree node the line is placed on. Null when no
  node received it, on a sub-total or a net line the statement prints, and on
  every line of an `unfooted` statement.
* `filed_values`: the line's figure per period as that node counts it, positive
  in the direction of the node's `effect`: the reduction a contra line prints
  is filed as a positive figure on its `subtracts` node. Null when
  `filed_under` is null.

### `payload.measures`

Each is one figure per period, null where the period has none, and null as a
whole when the statement states no such figure. On a `mapped` statement each
figure the tree states is the tree's own. On an `unfooted` statement they are
the figures the statement prints.

* `total_assets`: total assets.
* `current_assets`: total current assets.
* `noncurrent_assets`: total non-current assets.
* `total_liabilities`: total liabilities, current liabilities plus long-term
  liabilities.
* `current_liabilities`: total current liabilities.
* `longterm_liabilities`: total long-term liabilities.
* `mezzanine_equity`: mezzanine equity.
* `total_equity`: total equity.
* `total_liabilities_and_equity`: total liabilities and equity, the total the
  statement prints.
* `working_capital`: working capital, current assets less current liabilities.

### `payload.unmapped_lines[]`

* `key`: the `key` of a member of `lines`.
* `section`: the section of the statement the line prints in, as on a node:
  `current_assets`, `noncurrent_assets`, `current_liabilities`,
  `longterm_liabilities`, `mezzanine_equity` or `equity`. Null when the line
  prints outside every section, or the statement's sections could not be read.
* `suggested_account_id`: reserved for an account suggested for the line.
  Null.

### The list envelope

* `data`: the page: one mapping per document, each as the retrieve returns it
  for that document, ordered by the document's creation time, newest first.
* `limit`: the page size applied: `limit` as given, 1 to 25, or 10 when none
  was.
* `next_cursor`: an opaque string to pass as `cursor` for the next page. Null
  when there are no more mappings.
* `pending_document_ids`: the ids of the balance sheets of the borrower, or of
  the loan when `loan_id` is given, that have no mapping yet and whose first
  mapping is being prepared, newest document first. A statement nobody has
  asked for is prepared by the read that finds it. Empty when there are none.

The shape is declared on the endpoints' response schemas; every key listed
above is stated there.