The Statement Mapping object

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 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. 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 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.