> For the complete documentation index, see [llms.txt](https://docs.uptiq.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.uptiq.ai/document-ai/cookbooks/financial-spreading.md). # Spread a set of financials **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: ```json { "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" } ] } ``` {% hint style="warning" %} `BusinessFinancialStatement` takes a **structured** COA instead — an object keyed by statement, because one document contains both: ```json { "chartOfAccounts": { "BalanceSheet": [ ], "ProfitAndLossStatement": [ ] } } ``` Sending the flat array for that type maps the wrong accounts onto the wrong statement. {% endhint %} ### Step 2 — Or inherit an industry default ```json { "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: ```bash 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](/document-ai/cookbooks/async-extraction-and-polling.md). ### 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: ```bash jq '.extraction.result.extractedData | keys' record.json ``` ```json ["CompanyName", "DocumentDate", "Financials", "MultiplicativeFactorInWords", "MultiplicativeFactorRawNumber", "ReportingDates"] ``` {% hint style="danger" %} **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. {% endhint %} `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 ```bash 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: ```json { "content": "…", "documentTypes": [ { "documentType": "BalanceSheet" }, { "documentType": "ProfitAndLossStatement" } ] } ``` The children come back under one `extractionGroupId`, keyed by document type — see [Extract many documents at once](/document-ai/cookbooks/bulk-extraction.md). 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](/document-ai/guides-1/document-extraction.md). `form8825Addresses` targets specific properties directly and skips the property-discovery step: ```json { "documentType": "Form8825", "form8825Addresses": ["44 Harbour Road, Portland, OR"] } ``` ### Related pages * [Document Extraction](/document-ai/guides-1/document-extraction.md) — COA review in the UI, and the Form 8825 limits. * [Extraction API](/document-ai/developer-documentation/integration-guides/extraction.md) — `chartOfAccounts`, `industry`, `formTypes` in full. * [Process a loan application packet](/document-ai/cookbooks/loan-application-intake.md) — where the financials come from. * [Extract asynchronously and poll](/document-ai/cookbooks/async-extraction-and-polling.md) — the submission pattern used here. --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://docs.uptiq.ai/document-ai/cookbooks/financial-spreading.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.