Importing Bank Files

Guide 8: Importing Bank Files

Import transactions from your bank instead of manual entry -- including PDF statements

Overview

Importing bank files is the fastest way to get transactions into OtterLedger. Instead of typing each transaction, download a file from your bank and import it in seconds. OtterLedger handles duplicate detection, automatically cleans up messy bank descriptions into friendly payee names, and helps you categorize efficiently.

As of February 2026, OtterLedger also supports PDF statement import -- an AI-powered feature that extracts transactions directly from bank and credit card statement PDFs. No more re-typing from paper statements.

What you'll learn:

• Supported file formats (including PDF)
• Downloading files from your bank
• The import wizard
• PDF statement import with AI extraction
• Auto sign detection and friendly payee names
• Handling duplicates
• Post-import cleanup

Time required: 10-15 minutes per import (PDF statements may take slightly longer on first use)

Prerequisites

• At least one account in OtterLedger
• Access to your bank's website to download transactions
• For PDF import: an AI provider configured in Settings (Gemini or OpenAI recommended for best results; local LLM is also supported)

Supported File Formats

Which Format to Use?

1. OFX/QFX (recommended) -- Contains account info, well-structured, fastest to import
2. QIF -- Reliable standard format
3. PDF -- Great when your bank does not offer structured downloads, or for importing older archived statements
4. CSV -- Universal but may need column mapping
5. QBO -- For QuickBooks migration

Note: PDF import uses AI to extract transactions, so results depend on your configured AI provider. Cloud providers (Gemini, OpenAI) deliver the best accuracy. See Guide 48: PDF Statement Import for detailed PDF guidance.

Downloading from Your Bank

General Steps

1. Log in to your bank's website
2. Navigate to your account
3. Find "Download" or "Export" option
4. Select the date range
5. Choose format (OFX/QFX preferred)
6. Save the file

[Screenshot: Generic bank export interface]

Bank-Specific Tips

Chase:

• Account Activity > Download > QFX format

Bank of America:

• Statements > Download > Quicken (QFX)

Wells Fargo:

• Account Summary > Download > Quicken Format

Discover:

• Activity > Download > Excel or CSV

American Express:

• Statements > Download > OFX or CSV

Tip: If your bank only offers CSV, that works too -- OtterLedger will help you map the columns. If you only have a PDF statement, OtterLedger can extract the transactions using AI.

The Import Wizard

Starting an Import

1. Go to File > Import (or click Import in the Banking section)
2. Click Select File
3. Choose your downloaded file (.qif, .ofx, .qfx, .csv, .qbo, or .pdf)
4. Click Next

[Screenshot: Import wizard file selection step]

Step 1: File Analysis

OtterLedger analyzes the file and shows:

• File type detected (including PDF Bank Statement)
• Number of transactions found
• Date range
• Any issues detected

For PDF files, you will also see:

• The AI provider used for extraction (e.g., Python Extractor, Gemini, OpenAI, Local LLM)
• Parse confidence score
• Beginning and ending statement balances (if detected)
• Balance validation results

[Screenshot: File analysis results showing PDF metadata]

Step 2: Account Mapping

Map the imported transactions to an OtterLedger account:

1. Select the Target Account from the dropdown
2. If the file contains account info (common in OFX/QFX and PDF statements), OtterLedger suggests a match based on institution name, account number, and account type
3. Verify the account is correct
4. Optionally create a new account directly from this step
5. Click Next

[Screenshot: Account mapping step with suggested match]

Step 3: Field Mapping (CSV Only)

If you selected a CSV file, a field mapping step appears before the preview. See the CSV Import Details section below.

Step 4: Preview, Duplicate Detection & Friendly Names

OtterLedger shows a detailed preview of all transactions:

• All transactions to be imported with date, payee, and amount
• Friendly payee names extracted automatically (see below)
• Potential duplicates highlighted
• Suggested categories (if AI categorization is enabled)
• Transfer detection for inter-account movements
• Transaction totals: credits, debits, and net change
• Balance validation against statement balances (for PDF imports)

[Screenshot: Import preview with friendly names and duplicate warnings]

Friendly Payee Names:

Bank descriptions are often messy and hard to read. OtterLedger automatically cleans them up during import:

The preview shows both the original bank description (preserved as the memo) and the cleaned friendly name (used as the payee). You can edit either one before importing.

Auto Sign Detection:

OtterLedger analyzes the transaction amounts and compares them against the statement's beginning and ending balances to determine whether the signs are correct. If it detects that your bank uses an inverted convention (e.g., withdrawals shown as positive amounts), you will see a suggestion to flip signs. You can toggle the Flip Signs option in the preview to correct this.

The sign convention description updates live as you toggle:

• Standard: withdrawals negative (-), deposits positive (+)
• Flipped: positive becomes negative, negative becomes positive

Handling Duplicates:

For each flagged item, you can:

• Select/deselect individual transactions using the checkbox
• Select All / Deselect All to manage in bulk
• Review the duplicate match details (existing date, payee, amount)

AI Category Suggestions:

If AI categorization is enabled, each transaction may show a suggested category with:

• The category name
• Confidence level (Very High, High, Medium, Low)
• Which AI tier made the suggestion (Learned, Rules, ML, Local AI, Cloud AI)

Step 5: Import

Click Import to complete. OtterLedger shows real-time progress:

• Number of transactions imported
• Number skipped (duplicates or deselected)
• Any errors encountered

Click View Transactions to review.

[Screenshot: Import progress and completion]

PDF Statement Import

PDF import is powered by an AI extraction pipeline that reads your bank or credit card statement PDF and pulls out the transactions. This is especially useful when:

• Your bank does not offer OFX/QFX/CSV downloads
• You have archived paper statements scanned to PDF
• You want to import older statements that are only available as PDFs

How PDF Extraction Works

OtterLedger uses a tiered extraction pipeline:

1. Python PDF Extractor (tried first) -- Fast, free, works well for structured PDFs with clear table layouts
2. Cloud LLM (Gemini or OpenAI) -- Best for complex or unusual statement formats; recommended for highest accuracy
3. Local LLM -- Privacy-focused option; may struggle with complex multi-page statements

The system automatically detects:

• Bank name and account number
• Account type (checking, savings, credit card, etc.)
• Statement date range
• Beginning and ending balances
• All individual transactions with dates, descriptions, and amounts

Importing a PDF Statement

1. Go to File > Import and select your PDF file
2. OtterLedger extracts transactions using AI -- this may take 10-30 seconds depending on the provider and statement length
3. Review the extracted metadata: bank name, account type, date range, balances
4. Select or create the target account
5. Preview the transactions -- verify dates, amounts, and payee names look correct
6. Check the balance validation: does the net change of extracted transactions match the difference between beginning and ending balances?
7. Click Import

[Screenshot: PDF import showing extracted metadata and balance validation]

Balance Validation

For PDF imports, OtterLedger compares the sum of extracted transactions against the reported beginning and ending balances. If they match (within one cent), you will see a green confirmation. If they do not match, a warning appears -- this may indicate that some transactions were missed during extraction or that the statement has an unusual layout.

PDF Templates

If you regularly import PDFs from the same bank, OtterLedger can save a PDF parsing template. Templates remember the structural layout of a bank's statement format, making future imports faster and more reliable.

• When a matching template is detected, OtterLedger shows its name during file analysis
• Templates track usage count and success rate over time
• You can manage templates through the template editor (available when PDF template support is enabled in Settings)

Tip: If OtterLedger struggles to parse your PDF, look for the "Help Us Parse It" button during file analysis. This opens the template editor where you can define the table structure manually.

For complete PDF import guidance, including troubleshooting and best practices, see Guide 48: PDF Statement Import.

CSV Import Details

CSV files require column mapping since formats vary by bank.

Column Mapping

1. OtterLedger shows the first few rows of your file
2. For each column, select what it contains:
   • Date
   • Description/Payee
   • Amount
   • Amount (Credit)
   • Amount (Debit)
   • Category
   • Memo
   • Check Number
   • (Skip)

[Screenshot: CSV column mapping]

Common CSV Patterns

Single Amount Column:

• Negative = expense
• Positive = income

Separate Debit/Credit Columns:

• Map both columns
• OtterLedger combines them

Saving CSV Templates

For banks you import from regularly:

1. After mapping, click Save Template
2. Name it (e.g., "Chase Checking CSV")
3. Next import, select the template instead of remapping

Handling Duplicates

How Duplicates Are Detected

OtterLedger checks for matches based on:

• Date (within a few days)
• Amount (exact match)
• Description/Payee (similar text)
• Import ID (FITID from OFX files, if available)

If a saved duplicate resolution exists from a previous import (e.g., you marked a pattern as "Always Skip" or "Always Allow"), OtterLedger applies it automatically.

Duplicate Strategies

Option 1: Skip All Duplicates

• Safest option
• May miss legitimate similar transactions

Option 2: Review Each

• More work but more accurate
• Good for first few imports

Option 3: Import All

• Fastest but may create duplicates
• Only if you are sure there is no overlap

Fixing Duplicates After Import

If duplicates slip through:

1. Go to Transactions
2. Sort by date, look for identical entries
3. Delete the duplicate
4. Or use Tools > Find Duplicates

[Screenshot: Duplicate detection tool]

Post-Import Cleanup

After importing, review and clean up:

1. Categorize Transactions

Many imported transactions lack categories:

1. Go to Transactions
2. Filter by Uncategorized
3. Categorize each, or use bulk categorization
4. Let AI suggest categories if enabled (see Guide 23: AI Categorization)

2. Review Friendly Payee Names

OtterLedger automatically cleans up bank descriptions during import, but you may want to fine-tune some names:

• The Payee field shows the cleaned friendly name
• The Memo field preserves the original raw bank description
• Edit the payee name on any transaction, and OtterLedger learns your preference for future imports

3. Mark as Cleared

Imported transactions are marked "Cleared" by default. If you import pending transactions, update their status as needed.

4. Verify Balance

After import, check that your OtterLedger balance matches your bank:

1. Go to Accounts
2. Compare the balance to your bank's current balance
3. If different, look for missing or duplicate transactions

Tip for PDF imports: If the preview step showed a balance validation mismatch, double-check the imported transactions against your statement. A few transactions may have been missed or amounts may need correction.

Credit Card and Liability Account Imports

When importing transactions for credit card or other liability accounts, OtterLedger handles sign conventions automatically through the NegateStatementAmounts setting on the account.

• What it does: Flips the sign of all imported statement amounts so that charges appear as negative (money owed) and payments appear as positive (money paid)
• When it applies: Automatically enabled for credit card accounts; you can toggle it in the account editor for other liability accounts
• During import: If auto sign detection suggests flipping signs for a liability account, this is the underlying mechanism

You generally do not need to think about this -- OtterLedger handles it. But if imported amounts look inverted (charges showing as positive), check the NegateStatementAmounts setting in your account's properties.

Regular Import Routine

For ongoing bank imports:

1. Weekly or bi-weekly: Download and import transactions
2. Categorize uncategorized transactions
3. Verify the balance matches your bank
4. Monthly: Reconcile with your statement (see Guide 10: Reconciliation)

Tips & Best Practices

1. Import regularly -- Small, frequent imports are easier to manage than large backlogs

2. Use OFX when available -- It is more structured than CSV and does not require AI extraction like PDF

3. PDF is great for archives -- Use PDF import for old statements you cannot download in other formats

4. Check date ranges -- Ensure no gaps or overlaps between imports

5. Review duplicates carefully -- Legitimate similar transactions do happen (e.g., two identical coffee purchases on the same day)

6. Clean payee names early -- OtterLedger's friendly name extraction does most of the work, but your corrections teach it to do even better next time

7. Keep original files -- Store downloaded files in case you need to re-import

8. Use bank sync -- Consider SimpleFin for automatic imports (see Guide 9: Bank Connections)

9. Try Cloud AI for complex PDFs -- If local extraction struggles with your statement, switch to Gemini or OpenAI in Settings for better accuracy

10. Save templates for recurring imports -- Both CSV and PDF templates save time when you import from the same bank each month

Troubleshooting

Q: File won't import / format error

A:

• Verify the file downloaded correctly (try opening in a text editor for non-PDF files)
• Try a different format from your bank
• For CSV, check for special characters or encoding issues
• For PDF, ensure your AI provider is configured in Settings

Q: PDF extraction found zero transactions

A:

• Check that an AI provider is configured and working in Settings
• Try switching to a Cloud AI provider (Gemini or OpenAI) for better extraction
• The statement may have an unusual layout -- try the "Help Us Parse It" template editor if available
• See Guide 48: PDF Statement Import for detailed troubleshooting

Q: PDF extraction missed some transactions or amounts are wrong

A:

• Check the balance validation in the preview step -- a mismatch means some transactions may be missing
• Try a different AI provider (Cloud providers tend to be more accurate)
• You can manually add missing transactions after import
• For recurring imports from the same bank, creating a PDF template improves accuracy over time

Q: All transactions show as duplicates

A: You may have already imported this date range. Check existing transactions for the same dates.

Q: Balances don't match after import

A:

• Check for missing transactions (date range gap)
• Look for duplicates
• Verify opening balance is correct
• For PDF imports, check whether the balance validation passed in the preview step

Q: Amounts are inverted (charges positive, payments negative)

A:

• Use the Flip Signs toggle in the import preview
• For credit card accounts, verify the NegateStatementAmounts setting is enabled in the account editor
• OtterLedger's auto sign detection should suggest flipping when it detects an inversion

Q: Categories aren't being suggested

A:

• Enable AI categorization in Settings
• Import needs existing categorized transactions to learn from
• Cloud AI providers can categorize even without history

Q: Payee names are still messy after import

A:

• OtterLedger's friendly name extraction handles most common patterns
• Edit the payee name on any transaction to teach OtterLedger your preference
• Future imports will use your corrections automatically

Q: I need to import years of history

A:

• Import in chunks (6-12 months at a time)
• Oldest first, newest last
• Watch for duplicate detection between chunks
• PDF import works well for older archived statements

What's Next?

After mastering imports:

• Guide 9: Bank Connections (SimpleFin) -- Automatic imports without downloading files
• Guide 10: Reconciliation -- Verify imported data against your statements
• Guide 23: AI Categorization -- Automate transaction categorization
• Guide 48: PDF Statement Import -- In-depth guide for PDF extraction, templates, and troubleshooting

Need help? Visit the OtterLedger community at github.com/openledger or check the FAQ.