The Balance Sheet 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 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 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. 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. 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 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.