Data Management

Importing CSV & Excel

Upload CSV, Excel, statements, or receipts from Transactions → Import or Ask attach, map names, 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 a spreadsheet, bank statement, or receipt is the fastest way to get started with Nobleway.

You can bring files in two places:

Import (/app/import): the dedicated upload, review, and confirm workflow.
Chat (/app/query): attach or drag-and-drop a file in the chat. Receipt images become a draft card in the thread. CSV, Excel, and statement files continue as short chat steps (mapping, preview, confirm).

Nobleway detects the kind of file, validates rows, and lets you map accounts and categories before anything is saved to your ledger.

What you can import

Kind	Typical files	How rows are read
Spreadsheet	`.csv`, `.xlsx`	Deterministic parse. No AI.
Receipt	`.jpg`, `.jpeg`, `.png`, `.webp`	Vision AI extracts one draft transaction. You review every field.
Bank statement	`.pdf`, or statement images	Digital PDFs with a readable text layer are parsed on our servers first (no AI). Scanned PDFs and images use vision AI when needed. Re-uploading the same file reuses a prior extraction.

Nothing is written to the ledger until you confirm.

Spreadsheet formats (CSV & Excel)

CSV Files (.csv): Plain-text comma-separated files. Use canonical column names when you can, or common alternatives (for example Date, Transaction Type, Account Name). Nobleway inspects the file, maps headers automatically when possible, and asks you to confirm mapping when required.
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	Prefer `YYYY-MM-DD` (e.g. `2026-08-15`). Common day-first / month-first forms (e.g. `29/08/2026`) are auto-detected when unambiguous; otherwise Import asks you to choose a format. Excel date cells are accepted.	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.

Receipts and bank statements

Receipt images

Upload a clear photo or scan of a receipt. Vision AI proposes a single draft transaction. Review amount, date, merchant, and category, then confirm.

Bank statements

Upload a statement PDF or image. Nobleway:

Reuses a prior extraction when the same file was already processed for your household (no AI call).
Otherwise tries a deterministic text parse for digital PDFs.
Falls back to vision AI for scans and images when text parse finds no rows.

Bank narrations are cleaned into a short merchant, payment method (for example UPI or NEFT), and the full line in notes. Categories may be suggested from merchants your household has already confirmed.

Date format prompt

Statement and spreadsheet dates that look ambiguous (for example 01/09/2026 could be 1 September or 9 January) show a short prompt so you can choose day-first or month-first before import. Always check the preview.

When AI is used

AI is a last resort for files. Your spreadsheet and digital-statement text stay on Nobleway’s servers whenever possible.

Spreadsheet CSV/Excel: never. Parsed on our servers only.
Digital PDF statement with readable text: rule-based parse only. If rows are not recognized, export CSV/Excel instead. The file is not sent to AI.
Same statement file re-uploaded: not (checksum cache; no new AI call).
Scanned PDF / statement image (no usable text layer): yes, vision AI as last resort. You still confirm before save.
Receipt image: yes, vision AI for a single draft. You still confirm before save.

What is kept after upload

CSV / Excel: processed in the request. Nobleway does not keep a copy of the spreadsheet file after inspect/import finishes.
Statement PDF/image: kept in your household workspace so re-upload can reuse the extraction (checksum cache). Removed when you delete the household or complete account-closure cleanup. Not deleted immediately after a successful import.
Receipt images: kept as capture evidence with the related draft/transaction, and removed when that evidence or the household is deleted.

Details also appear in the Privacy Policy and Data & privacy.

The Import Workflow: Step-by-Step

Open Import (/app/import) and work through upload, review, then confirm. The same review steps apply when you attach a file in Chat; the chat guides you through mapping, preview, and confirm instead of the Import page.

Step 1: Upload Your File

Drag and drop (or choose) a .csv, .xlsx, receipt image, or statement PDF/image.
Nobleway detects the kind and shows what it found.

Step 2: Review and match names

Nobleway checks every row before anything is saved:

Date format: Choose day/month order when dates are ambiguous.
Matching names: If the file uses an account or category you do not have yet, 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 (or Import transactions for statements).
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.