Help Center / Data Setup

Import Actuals from CSV

Import a trial balance CSV, validate the results, and resolve common validation issues.

Use the CSV path when your source system is not connected directly to ClearBox FPA, or when you want to load a trial balance from a file instead of syncing from QuickBooks.

The import page puts both entry points side by side — QuickBooks Online for direct syncs and Trial Balance CSV for file uploads — along with Import History.

Start with the template

Download Template gives you the exact headers ClearBox FPA expects. If the entity already has accounts, it pre-fills those rows as a starting reference; a brand-new entity gets only the header row.

Required columns:

  • external_id
  • period
  • amount

period accepts common month formats such as 2026-03, 03/2026, and Mar 2026. Full dates inside that month also work, including month-end dates such as 2026-03-31 or 03/31/2026; ClearBox FPA normalizes them to the first day of that month.

external_id is the unique account ID ClearBox FPA matches on. For existing accounts, copy the template value exactly. For a new account, use a stable unique code you will keep reusing for that account, often the account number.

Optional account metadata:

  • account_number

If a row includes account_number, ClearBox FPA stores it on the matched account, whether that account already exists or is created during the import. Leaving account_number blank does not clear an existing account number.

If a row introduces a brand-new external_id, that row also needs:

  • account_name
  • account_type
  • account_subtype

ClearBox FPA uses those three fields to auto-create the missing account before it imports the balance. If the first row for a new external_id does not include them, the import fails.

Match the stored keys exactly — lowercase with underscores — even though the app displays them with capitals and spaces:

  • type expense for the displayed "Expense"
  • type operating_expense for "Operating Expense"
  • type accounts_receivable for "Accounts Receivable"

If the template already has a similar account, copy that row and change the ID, name, period, and amount. If the entity is brand new and the template is only headers, use the example row below as your pattern.

Example new-account row:

external_id,period,amount,account_name,account_type,account_subtype,account_number
7700,2026-03-01,1250.00,Software Subscriptions,expense,operating_expense,7700

If the same account appears on multiple rows because of multiple months or dimensions, keep the same external_id, account_name, account_type, account_subtype, and account_number on each of those rows when those fields are present.

Valid account_type values:

  • asset
  • liability
  • equity
  • revenue
  • expense

Valid account_subtype values by account_type:

  • asset: cash, investments, accounts_receivable, notes_receivable, inventory, prepaid_expenses, contract_assets, property_and_equipment, accumulated_depreciation, intangibles, goodwill, accumulated_amortization, rou_assets_operating, rou_assets_financing, deferred_tax_assets, other_assets
  • liability: accounts_payable, accrued_liabilities, contract_liabilities, deferred_tax_liabilities, notes_payable, lease_liabilities_operating, lease_liabilities_financing, other_liabilities
  • equity: owners_capital, contributions, distributions, retained_earnings, restricted_net_assets, aoci
  • revenue: revenue, interest_income, gain_loss_on_sale, other_income, oci
  • expense: cogs, operating_expense, depreciation_and_amortization, interest_expense, other_expense, income_tax_expense

Pick the correct source format

  • YTD - Debit/Credit means each month contains the cumulative year-to-date balance. This is the most common month-end trial balance export.
  • Monthly Activity - Debit/Credit means each month contains only that month's movement.

If February includes January activity, use YTD - Debit/Credit. If February stands on its own, use Monthly Activity - Debit/Credit.

Upload, then review before anything is written

Importing happens in two steps: prepare, then confirm. Choose the Source Format, select your file, and click Import. This prepares the import and opens a review screen — nothing is written to your books until you confirm.

The review screen shows exactly what the import will do before you commit:

  • Counts and period range — uploaded rows, balance rows, periods, and accounts, with the span of months covered.
  • A replace warning — existing actual balances in the imported periods are replaced; re-importing overwrites a period rather than stacking onto it.
  • Prepared balance rows — the normalized account / period / amount / dimension rows that will be written.
  • New Accounts — accounts that don't exist yet, to be created from the account_name / account_type / account_subtype columns.
  • Account Number Updates — rows that change an account's stored number.
  • New Dimension Values — dimension values that will be created on confirm.
  • Warnings — anything to look at before committing.

Read the New Accounts, New Dimension Values, and replace warning closely — these are where a CSV most often goes wrong. A typo'd external_id, for example, creates a duplicate account instead of updating the one you meant, and it surfaces here as an unexpected new account. When it looks right, click Confirm & Import — that is the only step that writes data, and the new row in Import History appears after it succeeds. Cancel discards the prepared import without touching your books.

Budget CSV imports use the same gate

A budget CSV (from Budgets) follows the identical flow: the upload prepares a draft, the review screen opens, and Confirm & Create Budget is the only write. The review also tells you if confirming will deactivate the current active budget for that fiscal year.

After importing, spot-check the period

Re-importing a period is safe: a confirmed import replaces that period's actuals, so you can correct the file and run it again. After a load, open Analysis and confirm the month reads correctly — the Income Statement for major revenue and expense lines, the Balance Sheet for cash, receivables, payables, and large balances, and Trial Balance for account-level detail.

If a month looks off, the usual cause is the wrong Source Format (YTD vs Monthly Activity) or an external_id or period that doesn't point where you intended. Fix the file and re-run.