sharpie/NeoCom

Fork 0

Files

Josh Myers 4681b1a3c8 initial commit

2026-04-09 20:36:10 -07:00

8.5 KiB

Raw Blame History

Example Bank CSV Files

Format 1: Date, Description, Amount

This is the most common format from bank exports.

Example: `bank_export_standard.csv`

Date,Description,Amount
2024-01-02,ACH WITHDRAWAL - RENT PAYMENT,5000.00
2024-01-03,DEPOSIT - ACME CORP PAYMENT,15000.50
2024-01-04,ELECTRONIC PAYMENT - UTILITIES,850.25
2024-01-05,"CHECK #1001 - OFFICE SUPPLIES, INC",1250.00
2024-01-08,BANK FEE,25.00
2024-01-10,DEPOSIT - CUSTOMER ABC LLC,3500.00
2024-01-12,ACH WITHDRAWAL - PAYROLL,12500.00
2024-01-15,WIRE TRANSFER OUT - SUPPLIER PAYMENT,8900.00
2024-01-16,DEPOSIT - RETURNED CHECK,500.00
2024-01-18,ONLINE PAYMENT - LOAN PAYMENT,2000.00
2024-01-20,ACH WITHDRAWAL - TAXES QUARTERLY,5000.00
2024-01-22,DEPOSIT - CONSULTING SERVICES,4500.00
2024-01-25,CHECK #1002 - EQUIPMENT LEASE,1800.00
2024-01-28,BANK INTEREST CREDIT,150.00
2024-01-30,ACH WITHDRAWAL - INSURANCE,750.00

How it's parsed:

Debit: Single amount (interpreted as DEBIT/withdrawal)
Credit: Single amount (if negative, interpreted as CREDIT/deposit)
All amounts are assumed DEBIT by default
Date format: YYYY-MM-DD

Format 2: Date, Description, Debit, Credit

This format explicitly shows debits and credits, common in business bank statements.

Example: `bank_export_debit_credit.csv`

Date,Description,Debit,Credit
2024-01-02,ACH WITHDRAWAL - RENT PAYMENT,5000.00,
2024-01-03,DEPOSIT - ACME CORP PAYMENT,,15000.50
2024-01-04,ELECTRONIC PAYMENT - UTILITIES,850.25,
2024-01-05,"CHECK #1001 - OFFICE SUPPLIES, INC",1250.00,
2024-01-08,BANK FEE,25.00,
2024-01-10,DEPOSIT - CUSTOMER ABC LLC,,3500.00
2024-01-12,ACH WITHDRAWAL - PAYROLL,12500.00,
2024-01-15,WIRE TRANSFER OUT - SUPPLIER PAYMENT,8900.00,
2024-01-16,DEPOSIT - RETURNED CHECK,,500.00
2024-01-18,ONLINE PAYMENT - LOAN PAYMENT,2000.00,
2024-01-20,ACH WITHDRAWAL - TAXES QUARTERLY,5000.00,
2024-01-22,DEPOSIT - CONSULTING SERVICES,,4500.00
2024-01-25,CHECK #1002 - EQUIPMENT LEASE,1800.00,
2024-01-28,BANK INTEREST CREDIT,,150.00
2024-01-30,ACH WITHDRAWAL - INSURANCE,750.00,

How it's parsed:

If Debit column has value: transaction type is DEBIT, amount is Debit value
If Credit column has value: transaction type is CREDIT, amount is Credit value
Both columns cannot have values in same row
Empty string or 0 in column means no transaction

Format 3: With Quoted Descriptions (Commas in Description)

Handles bank statements where description contains commas.

Example: `bank_export_quoted.csv`

Date,Description,Amount
2024-01-05,"CHECK #1001 - OFFICE SUPPLIES, INC, Springfield, IL",1250.00
2024-01-10,"DEPOSIT - CUSTOMER ABC LLC, Invoice #INV-2024-001, Reference: PO-5555",3500.00
2024-02-01,"WIRE TRANSFER - VENDOR XYZ, Invoice #INV-12345, Amount $8900, Reference Code ABC123",8900.00
2024-02-15,"ACH PAYMENT - MULTIPLE INVOICES, Details: INV-001 $500, INV-002 $750, INV-003 $1000",2250.00

Key Features:

Descriptions with commas are wrapped in quotes: "Description, with, commas"
Quotes are properly handled by the CSV parser
Real-world bank statements often include detailed transaction info

Format 4: Mixed with Escaped Quotes

Handles descriptions that contain both commas AND quotes.

Example: `bank_export_escaped_quotes.csv`

Date,Description,Amount
2024-01-20,"VENDOR INVOICE - Widget Corp, Item: ""Ultra Premium Widgets"", Qty: 500",2500.00
2024-02-10,"CUSTOMER DEPOSIT - ABC Corp, Receipt: ""2024-Feb-Invoice"", Amount: USD 5000",5000.00

Key Features:

Quotes inside quoted strings are escaped with double-quotes: "The ""thing"" is..."
Parser handles these correctly
Uncommon but can appear in detailed bank statements

API Request Examples

Parse CSV (Form Data)

curl -X POST http://localhost:3000/api/bank-transactions/parse-csv \
  -F "file=@bank_export_standard.csv"

Response:

{
  "success": true,
  "count": 15,
  "transactions": [
    {
      "transactionDate": "2024-01-02",
      "description": "ACH WITHDRAWAL - RENT PAYMENT",
      "transactionType": "DEBIT",
      "amount": 5000.00
    },
    {
      "transactionDate": "2024-01-03",
      "description": "DEPOSIT - ACME CORP PAYMENT",
      "transactionType": "DEBIT",
      "amount": 15000.50
    },
    ...
  ],
  "message": "Parsed 15 transaction(s) from CSV"
}

Import Transactions (JSON)

curl -X POST http://localhost:3000/api/bank-transactions/import \
  -H "Content-Type: application/json" \
  -d '{
    "bankAccountId": "550e8400-e29b-41d4-a716-446655440000",
    "transactions": [
      {
        "transactionDate": "2024-01-02",
        "description": "ACH WITHDRAWAL - RENT PAYMENT",
        "transactionType": "DEBIT",
        "amount": 5000.00,
        "referenceNumber": "ACH-123456",
        "oppositeParty": "Landlord LLC"
      },
      {
        "transactionDate": "2024-01-03",
        "description": "DEPOSIT - ACME CORP PAYMENT",
        "transactionType": "DEBIT",
        "amount": 15000.50,
        "referenceNumber": "INV-2024-001",
        "oppositeParty": "Acme Corp"
      }
    ]
  }'

Response:

{
  "success": true,
  "imported": 2,
  "message": "Successfully imported 2 transaction(s)"
}

Common Bank CSV Exports

Chase Business Banking

Typically uses: Date, Description, Amount

Date format: MM/DD/YYYY
Description includes transaction type and details
Single amount column (positive = debit)

Bank of America

Typically uses: Date, Description, Debit, Credit

Date format: MM/DD/YYYY
Description is brief
Explicit debit/credit columns

Wells Fargo Business

Typically uses: Date, Description, Amount

Date format: M/D/YYYY
Description is detailed
Amount is always positive

Quickbooks Export

Typically uses: Date, Reference, Amount, Description

Can be remapped to standard format
Date format: M/D/YYYY
Amount includes sign (negative = credit)

Data Quality Notes

Best Practices for CSV Uploads

Remove headers: API expects headers in first row
Check date format: Should be YYYY-MM-DD or MM/DD/YYYY
Consistent amounts: All positive numbers (debit/credit indicated by column)
No special formatting: Avoid currency symbols ($), commas in amounts (500.00, not 500,00)
Quoted descriptions: Use quotes if description contains commas
No summary rows: Remove total/balance rows at end of file

Invalid Examples (Will Fail)

Date,Description,$Amount
1/2/24,Rent Payment,"$5,000.00"
1/3/24,Deposit,15000.50

Problems:

Currency symbol in header ($Amount)
Non-standard date format (1/2/24)
Currency formatting in amount ($5,000.00)

Valid Examples (Will Succeed)

Date,Description,Amount
2024-01-02,Rent Payment,5000.00
2024-01-03,Deposit,15000.50

Testing Workflow

Step 1: Prepare CSV

Use one of the example files above or export from your bank.

Step 2: Parse for Preview

curl -X POST http://localhost:3000/api/bank-transactions/parse-csv \
  -F "file=@bank_export.csv"

Review the parsed transactions in the response.

Step 3: Adjust if Needed

If parsing fails, check:

CSV has required columns (Date, Description, Amount or Debit/Credit)
Date format is standard (YYYY-MM-DD or MM/DD/YYYY)
Descriptions with commas are quoted
No extra rows (headers, totals, etc.)

Step 4: Import

Once happy with preview, send parsed transactions to import endpoint.

curl -X POST http://localhost:3000/api/bank-transactions/import \
  -H "Content-Type: application/json" \
  -d '{
    "bankAccountId": "your-account-uuid",
    "transactions": [... from parse response ...]
  }'

Step 5: Verify in UI

Bank Transactions list view
Bank Account details
Cash position report

Troubleshooting

"CSV must have 'Date' and 'Description' columns"

Check header row for exact column names
Use: Date and Description (case-sensitive)
Or: date, description (lowercase works too)

"CSV must have 'Amount' or 'Debit'/'Credit' columns"

Format 1: Include Amount column
Format 2: Include both Debit AND Credit columns
Cannot mix formats in same file

"CSV file is empty"

Check that file was uploaded successfully
File must have at least header + 1 data row

"Cannot read property 'toLowerCase' of null"

Likely missing required columns
Verify CSV header row has Date and Description

Transactions show with wrong type (DEBIT vs CREDIT)

In Format 1 (single Amount column), all treated as DEBIT
Use Format 2 (Debit/Credit columns) for mixed transaction types
Or ensure negative amounts are handled correctly

8.5 KiB Raw Blame History