Spread a set of financials

Map extracted line items onto your chart of accounts.

Goal. Extract a borrower's balance sheet, P&L and tax returns, and get the line items mapped onto your chart of accounts rather than whatever the borrower's accountant called them.

Spreading is the step that makes financials comparable. Two businesses will describe the same thing as "Trade Debtors" and "Accounts Receivable"; a credit model needs them in the same row. Document AI can do that mapping during extraction if you tell it what your accounts are.

Before you start

• An API key, exported as $DOCAI_API_KEY.

• Financial documents — BalanceSheet, ProfitAndLossStatement, BusinessFinancialStatement.

• Your chart of accounts, or an industry to inherit a default one from.

Step 1 — Supply your chart of accounts

Three ways, in order of directness:

Property	Use when
chartOfAccounts	You have the accounts to hand
chartOfAccountsUrl	The COA lives at a URL the platform can fetch. Only consulted when chartOfAccounts is absent
industry	You want the platform's default COA for a sector

The flat form is a list of accounts:

{
  "documentType": "BalanceSheet",
  "content": "…",
  "chartOfAccounts": [
    { "accountId": "1100", "accountName": "Cash and Cash Equivalents" },
    { "accountId": "1200", "accountName": "Accounts Receivable" },
    { "accountId": "1300", "accountName": "Inventory" },
    { "accountId": "2100", "accountName": "Accounts Payable" },
    { "accountId": "2200", "accountName": "Short-Term Debt" },
    { "accountId": "3100", "accountName": "Retained Earnings" }
  ]
}

BusinessFinancialStatement takes a structured COA instead — an object keyed by statement, because one document contains both:

{
  "chartOfAccounts": {
    "BalanceSheet": [ ],
    "ProfitAndLossStatement": [ ]
  }
}

Sending the flat array for that type maps the wrong accounts onto the wrong statement.

Step 2 — Or inherit an industry default

{
  "documentType": "BalanceSheet",
  "content": "…",
  "industry": "manufacturing"
}

Useful for a first pass, or where you have no COA of your own. A supplied chartOfAccounts is more precise — the industry default cannot know your account numbering.

Step 3 — Extract

Financial documents are the slow case, so use the asynchronous endpoint:

curl -X POST "https://api-docai-uat.uptiq.ai/extract" \
  -H "X-Api-Key: $DOCAI_API_KEY" \
  -H "Content-Type: application/json" \
  --data-binary @spread.json

Then poll or receive the webhook — see Extract asynchronously and poll.

Step 4 — Read the line items

Financial extractions return structured collections rather than flat fields. On our test balance sheet, extractedData held CompanyName, DocumentDate, ReportingDates, Financials, and the multiplicative-factor fields:

jq '.extraction.result.extractedData | keys' record.json

["CompanyName", "DocumentDate", "Financials",
 "MultiplicativeFactorInWords", "MultiplicativeFactorRawNumber", "ReportingDates"]

Do not ignore the multiplicative factor. Financial statements are routinely presented in thousands or millions, and MultiplicativeFactorInWords / MultiplicativeFactorRawNumber are how that is reported. A figure of 356.55 on a statement headed "in thousands" is 356,550 — reading the raw number without applying the factor understates the balance sheet by three orders of magnitude.

ReportingDates matters just as much: a balance sheet is a position at a date, and comparing two borrowers at different dates, or mixing a 9-month P&L with a 12-month one, produces confident nonsense.

Step 5 — Check what did not map

jq '.extraction.result.extractionMetrics
    | {accuracyScore, completenessScore, missingFields, failedRules}' record.json

missingFields is the important one when spreading. An account in your COA with nothing mapped to it is either genuinely absent from the statement or was described in a way the extraction did not recognise — and those two cases need different responses.

A workable policy:

Signal	Action
High accuracy, no missing fields	Accept
Missing fields that your model needs	Review those line items specifically
consistencyScore low	The statement may not balance — check before trusting any of it
Low documentQuality.level	Re-scan rather than re-extract

Step 6 — Multi-period and multi-statement sets

Where one file holds several statements, use documentTypes to extract each separately in one job:

{
  "content": "…",
  "documentTypes": [
    { "documentType": "BalanceSheet" },
    { "documentType": "ProfitAndLossStatement" }
  ]
}

The children come back under one extractionGroupId, keyed by document type — see Extract many documents at once.

For tax returns, formTypes narrows extraction to the forms you care about, which is worth doing on a return that runs to dozens of schedules.

Form 8825 and rental properties

Real-estate lending has a wrinkle worth knowing. Form 8825 extraction is limited to the first 50 properties in full, with basic information only beyond that — see Document Extraction. form8825Addresses targets specific properties directly and skips the property-discovery step:

{ "documentType": "Form8825", "form8825Addresses": ["44 Harbour Road, Portland, OR"] }

Related pages

• Document Extraction — COA review in the UI, and the Form 8825 limits.

• Extraction API — chartOfAccounts, industry, formTypes in full.

• Process a loan application packet — where the financials come from.

• Extract asynchronously and poll — the submission pattern used here.