Statement mapping | SpreadSpace

The mapping covers profit and loss statements. Reading one requires a plan that includes statement mapping; other plans get 403 with statement_mapping_not_in_plan.

What a mapping is

A mapping is one profit and loss statement placed on the workspace’s chart of accounts. Every line the statement prints is filed on an account, every section and account carries its figure per period, the headline measures (gross profit, operating income, income before income taxes, net income) are stated, and every figure says where in the document it comes from. The body is a contract you can check: the tree adds up to the cent by the rules under The arithmetic, and what it adds up to is the bottom line the statement prints.

For every usable profit and loss statement a mapping is prepared after extraction. It is read by document id, or listed per borrower, in the Statement Mappings group of the API reference. Both reads need the extractions:read scope.

Operation	Returns
`GET /api/borrowers/{borrowerId}/extractions/{docId}/mapping`	One document’s latest mapping, the Statement Mapping object.
`GET /api/borrowers/{borrowerId}/extractions/mappings`	A borrower’s mappings, one per document, newest document first, as `{ data, limit, next_cursor, pending_document_ids }`. `?loanId=` narrows it to one loan; `limit` is 1 to 25 and defaults to 10.

curl https://api.spreadspace.app/api/borrowers/4a2c8e1f6b3d5a7c9e0f1b2d/extractions/7a1d4e9c2b3f4a5d8e6c1b0f/mapping \
  -H "Authorization: Bearer ss_live_..."

The response carries the mapping’s identity and versions on the envelope and the statement itself in payload:

Key	What it says
`mapping_id`	The mapping’s id. A statement gets a new mapping, under a new id, whenever its extraction, the workspace’s chart of accounts, caption rules or export map, or the mapping logic changes.
`status`	`ready` or `unmappable`.
`payload.mapping_state`	On a ready mapping, `mapped` or `unfooted`.
`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.
`chart_document_version`, `chart_rules_version`	The versions of the workspace’s chart of accounts and caption rules the mapping was made under, the `version` and `rules_version` that `GET /api/chart-of-accounts` returns.
`stale`	True when the chart of accounts, the caption rules, the export map or the mapping logic changed after this mapping was made.

Every figure is a decimal string with exactly two decimal places, and every values array, every measure and every entry of foot run in the order of payload.periods, so position i of each belongs to period i. See the value conventions.

When a mapping is ready

A mapping is prepared after the statement’s extraction, so it follows extraction.ready. Three signals say when it is ready:

The event. extraction.mapped fires once for every mapping: the first, and each one made again. reason says why: first for the document’s first mapping, extraction when the extraction was revised, chart when the workspace’s chart of accounts, caption rules or export map changed, logic when the mapping logic changed, and correction when none of those moved and the statement was corrected in the workspace. The event is a pointer: the document, its borrower and loan, the mapping_id, status and mapping_state, the versions and the time, never a figure. Read the mapping it names and let it replace the copy you hold. See Webhooks for the envelope, the fields and the delivery rules.
The retrieve. While the statement’s first mapping is being prepared, the retrieve answers 404 with a Retry-After header saying how many seconds to wait before reading again. A statement nobody has asked for is prepared by the read that finds it, so the first read of a document can answer this way. A 404 without Retry-After means no mapping is being prepared: the document is not a profit and loss statement, or is not one you can see.
The list. pending_document_ids names the documents of the borrower, or of the loan when loanId is given, whose first mapping is still being prepared. Read the list until it is empty and every statement the borrower holds is in data.

A mapping that reads stale: true is still the latest one stored, served while a fresh one is prepared: the chart of accounts, the caption rules, the export map or the mapping logic moved after it was made. Read again to receive the new one, or wait for the extraction.mapped that announces it.

curl "https://api.spreadspace.app/api/borrowers/4a2c8e1f6b3d5a7c9e0f1b2d/extractions/mappings?loanId=7d1e3b5a9c2f4e6b8d0a3c5e&limit=25" \
  -H "Authorization: Bearer ss_live_..."

Mapped, unfooted, unmappable

`status`	`mapping_state`	What you hold	What to do
`ready`	`mapped`	The statement’s lines were placed on the chart of accounts and walk to its printed bottom line. `tree` carries the statement on the chart, every placed line names the node it is filed on, and the measures are the tree’s own figures.	Post the tree: each account’s figure per period, with its `external_code` where your export map gives one.
`ready`	`unfooted`	The lines could not be made to walk to the printed bottom line. `tree` is null and `filed_under` is null on every line; `lines` and `measures` state the statement as printed, and `foot` says by how much each period misses.	Hold the statement for review, or post the printed measures. A statement corrected in the workspace is mapped again, and `extraction.mapped` says so with `reason: correction`.
`unmappable`	none	The statement could not be read as a profit and loss statement at all. `error_code` is `unmappable` and `payload` is null.	Nothing to post. The document’s own profit loss statement read still returns its extraction.

The arithmetic

The tree is a contract you can recompute from the body, to the cent.

Every figure on a section or an account is positive in the direction of the node’s effect, adds or subtracts: a positive figure on a cost is a cost, a negative one is a credit against it, and a gain or loss on dispositions is positive for a gain.
A node’s figure is the sum of the nodes under it, measures aside, each added when its effect is the node’s own and subtracted otherwise, plus the filed_values of the lines placed on the node itself, plus its unitemized. A null counts as no figure.
unitemized is the part of a node’s figure that no printed line accounts for: the statement prints a total and no detail for part of it, or the printed figures were rounded. It is 0.00 where the lines account for all of it.
Gross profit is revenue less cost of goods sold. Operating income is gross profit less operating expenses. Income before income taxes is operating income plus other income, less other expenses, less interest, plus gains on dispositions. The net income row is the bottom line the statement prints.
The sections at the top of the tree, measures aside, each counted by its effect, sum to foot.line_sum, and foot.residual is printed_bottom_line less line_sum. On a mapped statement the residual is within foot.tolerance, what the footing allows 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 printed in whole dollars, not a defect.
A line’s values are the figures as the statement prints them, in the statement’s own sign presentation. Its filed_values are what the tree counts, positive in the direction of the node’s effect.

A worked example

A statement for the year ended December 31, 2025 prints ten lines, in whole dollars:

Printed line	Figure	Placed on
Consulting fees	418,600.00	`pl.revenue.sales`
Total income	418,600.00	none, a total
Rent	72,000.00	`pl.opex.rent`
Salaries	196,300.00	`pl.opex.labor.salaries`
Insurance	14,900.00	`pl.opex.insurance`
Insurance refund	(1,200.00)	`pl.opex.insurance`, at `-1200.00`
Total expenses	284,000.00	none, a total
Net operating income	134,600.00	none, a total
Interest expense	9,800.00	`pl.interest`
Net income	124,801.00	none, the bottom line

Its tree, showing the three sections that carry a figure (the other five are listed with null figures), the two measure rows, and the accounts the lines landed on:

Node	`key`	`effect`	`values`	`unitemized`
Net Revenue	`pl.revenue`	`adds`	`418600.00`	`0.00`
Sales	`pl.revenue.sales`	`adds`	`418600.00`	`0.00`
Gross profit	`m:gross_profit`	null	`418600.00`	null
Operating expenses	`pl.opex`	`subtracts`	`284000.00`	`2000.00`
Labor cost	`pl.opex.labor`	`subtracts`	`196300.00`	`0.00`
Salaries and wages	`pl.opex.labor.salaries`	`subtracts`	`196300.00`	`0.00`
Rent	`pl.opex.rent`	`subtracts`	`72000.00`	`0.00`
Insurance	`pl.opex.insurance`	`subtracts`	`13700.00`	`0.00`
Interest expense	`pl.interest`	`subtracts`	`9800.00`	`0.00`
Net income	`m:net_income`	null	`124801.00`	null

Read it with the rules above:

pl.opex.insurance holds two printed lines. Insurance is filed at 14900.00. Insurance refund is printed as (1,200.00), a credit against the cost, so its values entry is -1200.00 and so is its filed_values entry: a negative figure on a subtracts node. The account’s figure is 14900.00 + (-1200.00) = 13700.00, and its unitemized is 0.00.
pl.opex holds no line of its own. Its accounts sum to 196300.00 + 72000.00 + 13700.00 = 282000.00, but the statement prints Total expenses of 284000.00 and gives no line for the other 2000.00, so the section’s unitemized is 2000.00 and its figure is 284000.00, the total as printed.
Gross profit is revenue less cost of goods sold. This statement prints no cost of goods sold, so m:gross_profit is 418600.00.
Operating income is 418600.00 - 284000.00 = 134600.00, the Net operating income the statement prints. Income before income taxes is 134600.00 - 9800.00 = 124800.00: no other income, no other expenses, no gains on dispositions.
m:net_income is 124801.00, the bottom line the statement prints.

The two lines placed on the insurance account, as lines carries them:

[
  {
    "key": "pl:insurance",
    "label": "Insurance",
    "depth": 0,
    "is_total": false,
    "values": ["14900.00"],
    "sources": [{ "kind": "printed", "document_id": "8e2f5a7c1b4d4c6e9a0b3d5f", "address": "lines.4.0", "pages": [1] }],
    "filed_under": "pl.opex.insurance",
    "filed_values": ["14900.00"]
  },
  {
    "key": "pl:insurance refund",
    "label": "Insurance refund",
    "depth": 0,
    "is_total": false,
    "values": ["-1200.00"],
    "sources": [{ "kind": "printed", "document_id": "8e2f5a7c1b4d4c6e9a0b3d5f", "address": "lines.5.0", "pages": [1] }],
    "filed_under": "pl.opex.insurance",
    "filed_values": ["-1200.00"]
  }
]

The foot for the period:

{
  "printed_bottom_line": "124801.00",
  "printed_bottom_line_source": {
    "kind": "printed",
    "document_id": "8e2f5a7c1b4d4c6e9a0b3d5f",
    "address": "lines.9.0",
    "pages": [1]
  },
  "line_sum": "124800.00",
  "residual": "1.00",
  "tolerance": "1.50"
}

line_sum is the three sections by their effect: 418600.00 - 284000.00 - 9800.00 = 124800.00. The statement prints 124801.00, so the residual is 1.00. The tolerance is 1.50: a dollar, plus half a dollar for the one printed figure the walk counts below the operating income line, the interest expense. The residual is within it, so the statement is mapped: it was printed in whole dollars, and a dollar of rounding sits between its lines and its bottom line. measures state the tree’s own figures: revenue 418600.00, gross_profit 418600.00, operating_expenses 284000.00, operating_income 134600.00, pretax_income 124800.00, net_income 124801.00.

Sources

Every figure states where it comes from. A source on a tree node, on a printed line or on the foot carries:

kind: printed when the document prints the figure, derived when the figure is computed 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.
address: a printed figure’s place in the document’s report data, for example lines.4.0 for the figure of lines[4] in the first period column of the profit loss statement read, so a mapped figure joins back to the printed line it came from. Null on a derived figure.
pages: the pages the figure is printed on, numbered from 1. A derived figure lists the pages of the figures it is computed from.

A node’s sources and a line’s sources run in the order of periods, one entry per figure, null where the figure is null.

Marks and unmapped lines

Three lists on a tree node name its printed lines:

member_keys: every printed line the node holds, those on the nodes under it included; direct_member_keys: the lines placed on the node itself. Each is the key of a member of lines.
flagged_keys: lines 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; the mark says a person should look.
reclassified_keys: always empty. The key stays so the shape of a node is unchanged.

unmapped_lines lists the printed lines that carry a figure and that no account received, each with the section it prints in (revenue, cogs, other_income, opex, other_expenses, interest, dispositions or taxes, or null when the line prints outside every section). On a mapped statement such a line is counted on its section’s own row, so the tree still foots; suggested_account_id is reserved and null. On an unfooted statement no line is placed, and unmapped_lines names every line that would have been.

unmapped_export_account_ids lists the account ids the workspace’s export map gives a code that this mapping’s tree does not list, so a map entry that names an account outside the profit and loss chart is visible from the mapping itself.

The chart of accounts

The tree is the workspace’s chart of accounts with this statement’s figures. GET /api/chart-of-accounts returns the chart document the workspace saved, its version, the rules_version of its caption rules and its active_export_system. Until the workspace saves a chart, chart is null, version is 0 and the platform’s accounts below apply. A workspace’s own arrangement keeps every platform account it leaves out in force, and the tree of every mapping lists the accounts in force with their ids, so the tree is the authority on which accounts exist for that statement. The read needs the chart_of_accounts:read, chart_of_accounts:write or extractions:read scope.

curl https://api.spreadspace.app/api/chart-of-accounts \
  -H "Authorization: Bearer ss_live_..."

A section that has no accounts of its own holds its lines on the section’s row, whose key is pl. followed by the section (pl.interest) and whose account_id is null.

The platform’s accounts

The account ids an export map keys on, section by section, in tree order. Sub-accounts are indented under their parent.

Net Revenue

The revenue section, key pl.revenue.

Account id	Label
`pl.revenue.sales`	Sales
`pl.revenue.returns_allowances`	Returns and allowances
`pl.revenue.unclassified`	Unclassified
`pl.revenue.other`	Other

COGS

The cogs section, key pl.cogs.

Account id	Label
`pl.cogs.purchases`	Purchases
`pl.cogs.labor`	Labor (COGS)
`pl.cogs.depreciation`	Depreciation
`pl.cogs.inventory`	Inventory
`pl.cogs.other_costs`	Other costs