Data ManagementNobleway Docs

Importing CSV & Excel

Upload historical statements as CSV or Excel, map accounts and categories, and skip duplicates.

Data Pipeline

5-Stage Statement Ingestion Flow

File Upload

Drop CSV or Excel (.xlsx) file into workspace

Sheet & Headers

Select transaction tab and confirm column headers

Entity Mapping

Map payees to people, categories, and accounts

Duplicate Check

Deterministic hash matching skips already-imported rows

Atomic Commit

Commit verified rows cleanly into ledger

Migrating your financial records from an existing spreadsheet or another personal finance tool is the fastest way to get started with Nobleway.

Nobleway provides an Import tool (/app/import) that accepts standard CSV files and Excel workbooks (.xlsx), validates your records, catches duplicates, and allows you to map accounts and categories before saving to your ledger.

Supported File Formats

Nobleway accepts two file formats:

CSV Files (.csv): Plain-text comma-separated files. Capitalization of column headers does not matter.
Excel Workbooks (.xlsx): Standard modern Excel spreadsheets.

Column names Nobleway expects

Use these headers when you can. Extra columns are ignored:

Column Header	Required?	Accepted Values & Format	Description
`occurred_on`	Yes	`YYYY-MM-DD` (e.g. `2026-08-15`) or Excel date cell	The calendar date the transaction took place.
`type`	Yes	`Expense`, `Income`, or `Transfer`	The transaction type. Capitalization is flexible (e.g. `expense`).
`amount`	Yes	Positive decimal number (e.g. `45.50`)	The monetary amount. Must always be positive.
`currency`	No	3-letter currency code (e.g. `USD`, `EUR`, `INR`)	Defaults to the workspace or account currency.
`account`	No*	Account name in your workspace	The account used. (Required for Expense/Income if not mapped).
`category`	No*	Category or subcategory name	Category name. (Required for Expense/Income).
`subcategory`	No	Subcategory name	Optional specific subcategory if split from parent category.
`person`	No	Household person name (e.g. `Sarah`)	Associates the transaction with a specific household person.
`merchant`	No	Freeform text (e.g. `Costco`, `Starbucks`)	The business or vendor where money was spent.
`recipient`	No	Freeform text	The recipient of an expense or transfer.
`notes`	No	Freeform text	Memos, remarks, or personal tags.
`payment_method`	No	Text (e.g. `Credit Card`, `Debit`, `Cash`)	Contextual payment method label.
`source_account`	No*	Account name	For Transfers: the account where money left.
`destination_account`	No*	Account name	For Transfers: the account where money arrived.
`external_reference_id`	No	Unique alphanumeric ID	Bank transaction ID. Used for strict duplicate detection.

Example CSV Layout

Here is an example of a properly formatted CSV file:

CSV

occurred_on,type,amount,account,category,merchant,person,notes
2026-08-01,Income,4500.00,Main Checking,Salary,Acme Corp,Sarah,Monthly paycheck
2026-08-02,Expense,85.20,Main Checking,Groceries,Trader Joe's,Sarah,Weekly shopping
2026-08-03,Expense,12.50,Sapphire Card,Food & Dining,Blue Bottle,Alex,Morning coffee
2026-08-05,Transfer,500.00,,,Savings,Sarah,Monthly emergency fund transfer

Excel Workbook (`.xlsx`) Specific Rules

If you are importing an Excel workbook, keep the following behaviors in mind:

Cached Values Only (No Live Formulas)

Nobleway reads the pre-calculated cached values inside Excel cells. It does not execute dynamic formula scripts.

Tip: Before uploading your spreadsheet, open it in Excel or Google Sheets, ensure formulas evaluate, and save the file so that cell value caches are up to date.

Automatic Non-Transaction Sheet Filtering

Many household budget spreadsheets include summary dashboards or reference tables. Nobleway automatically detects and ignores common non-transaction sheet names, including:

Dashboard, Monthly Stats, Accounts, Loans & Goals, Lists, Help, and Info.

The Import Workflow: Step-by-Step

Open Import (/app/import) and work through three stages: upload, review, then confirm.

Step 1: Upload Your File

Drag and drop your .csv or .xlsx file into the upload zone.
Nobleway reads the file and shows how many rows it found.

Step 2: Review and match names

Nobleway checks every row before anything is saved:

Matching names: If the file uses an account or category you do not have yet (for example, "Whole Foods" vs "Groceries"), you can match it to an existing name or create a new one.
Row errors: Missing dates, amounts, or accounts are flagged with the row number and a short explanation.
Duplicates: Rows that look like existing transactions (same date, amount, account, and bank reference when present) are flagged so you can skip them.

Step 3: Confirm Import

Once mappings and errors are resolved, click Confirm import.
The approved rows are saved.
Balances and dashboard totals update.

What Happens After Import?

History: Nobleway records when the import happened and how many transactions were added.
Historical Queries: All imported records immediately become searchable via Asking Questions and appear in Recording Transactions history.
Opening date: Transactions dated before the account’s Opening as of date still appear in history, but they do not change the current balance. See Accounts & Opening Balances for details.

Next Steps

Review how accounts and opening dates work: Accounts & Opening Balances.
Enter new daily transactions conversationally: Natural-Language Capture.
Query your newly imported transaction history: Asking Questions.

Need help or spotted an issue?

Nobleway is currently in public beta. If you notice inaccuracies or need guidance on household ledger setups, reach out directly to our engineering team at support@nobleway.app.