> 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/statement-mappings/object/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.spreadspace.app/_mcp/server.

# The Statement Mapping object

> A profit and loss statement 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 profit and loss statement 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 profit and loss statement
after extraction; [Statement mapping](/api/statement-mapping) is the guide to
reading one, with the arithmetic worked through.

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 statement mapping](/api/api-reference/statement-mappings/get-statement-mapping)

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

GET`/api/borrowers/:borrowerId/extractions/:docId/mapping`

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

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

GET`/api/borrowers/:borrowerId/extractions/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 profit and loss statement 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, `profit_and_loss`.
* `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 walk to its printed bottom line, 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.
* `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 revenue down to net
  income: sections, the accounts under them and measure rows such as gross
  profit, 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 its lines may walk to a bottom line a
few dollars from the one it prints. `tolerance` is how far apart the two may
be, and on a `mapped` statement `residual` is within it. On an `unfooted`
statement the residual is the amount by which the printed lines miss the
printed bottom line.

* `printed_bottom_line`: the bottom line the statement prints for the period,
  its net income. Null when it prints none.
* `printed_bottom_line_source`: where the printed bottom line comes from, a
  source as described under [Sources](#sources). Null when the statement prints
  none.
* `line_sum`: the bottom line the statement's lines walk to. On a `mapped`
  statement it is the sum of the nodes at the top of the tree, measures aside,
  each counted by its `effect`. Null when the lines give no such walk.
* `residual`: `printed_bottom_line` less `line_sum`. `0.00` when the two agree.
  Null when either is null.
* `tolerance`: the difference the footing allows in the period, for the
  rounding of printed figures: a dollar, plus half a dollar for each printed
  figure the walk counts below the operating income line. A residual of `3.00`
  beside a tolerance of `8.50` is a statement 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 computed from figures the document prints.
* `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, for
  example `lines.12.0` for the figure of `lines[12]` in the first period
  column, so the figure joins to the line the profit loss statement read
  returns. Null on a derived figure.
* `pages`: the pages of the document the figure is printed on, numbered from
  1, in ascending order. A derived figure lists the pages of the figures it is
  computed 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 gross profit
(`measure`). Rows nest through `children`. The tree can be recomputed from the
payload, to the cent, by the rules on the [Statement mapping](/api/statement-mapping#the-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 `pl.` 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: `revenue`, `cogs`,
  `other_income`, `opex`, `other_expenses`, `interest`, `dispositions` or
  `taxes`. 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: `gross_profit`, `operating_income`,
  `pretax_income`, `net_income`, `ebit`, `adjusted_ebit`, `ebitda`,
  `adjusted_ebitda`, `ebita` or `adjusted_ebita`. 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 net
  income. A positive figure on an `adds` node raises it, on a `subtracts` node
  lowers it. 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.
* `flagged_keys`: the keys of the node's printed lines that are marked for a
  reader's attention: an expense line whose caption names no expense
  (uncategorized, suspense), names something that is not an expense (an
  owner's draw, a loan payment, an asset purchase), or is a bare catch-all such
  as other or miscellaneous. 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. 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, 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`. 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
revenue, gross profit, operating expenses, operating income, income before
income taxes and net income are the tree's own figures. On an `unfooted`
statement they are the figures the statement prints.

* `revenue`: net revenue.
* `gross_profit`: gross profit.
* `operating_expenses`: total operating expenses.
* `operating_income`: operating income.
* `pretax_income`: income before income taxes.
* `net_income`: net income, the bottom line the statement prints.
* `ebitda`: earnings before interest, taxes, depreciation and amortization.
* `noi`: net operating income, stated for a rental property's statement only.
  Null for every other statement.

### `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.
  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 documents of the borrower, or of the
  loan when `loanId` 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.

> A profit and loss statement 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.