Weave Code
Data Importer Laravel Package
firefly-iii/data-importer
A companion tool for Firefly III that imports transactions and account data from banks and CSV files, with a web-based setup and support for multiple sources to help you migrate or keep your finances in sync.
Firefly III Data Importer is a companion tool for Firefly III that brings external financial data into your personal finance setup without manual entry. It provides a guided web interface for mapping, validating, and running imports, then submits results through the Firefly III API.
- Import CSV files with configurable column mapping and date/amount formats
- Connect to banks via Nordigen/GoCardless and other supported providers
- Detect and skip duplicates to keep records clean
- Run as a standalone Docker service alongside Firefly III
- Review import jobs and troubleshoot errors in the UI
Frequently asked questions about Data Importer
- What is firefly-iii/data-importer, and can I install it with Composer into my existing Laravel app?
- It is a standalone Laravel web application for importing financial data into Firefly III, not a library you require into an existing codebase. There is no supported SDK, service contract, or embeddable component, so Composer-requiring it into your own app is not the intended integration path. Realistic options are running it as a companion service, forking it under AGPL terms, or reusing its patterns as reference architecture.
- Which PHP and Laravel versions does the Firefly III Data Importer support?
- It targets PHP 8.x with a modern Laravel release, Blade server-rendered views, a relational database, and a queue worker. The importer follows Firefly III API v1, and its supported Laravel version moves with upstream releases. Pin the Firefly III, importer, and API version triple together and read the release notes before upgrading any one of them.
- How do I install and run the Firefly III Data Importer with Docker?
- A Docker image exists and is the recommended path for self-hosted deployments. You need a reachable Firefly III instance over HTTPS, a database for the importer, a running queue worker, and a way to trigger runs from the web UI or the CLI. A historical backfill followed by recurring scheduled imports is a well-trodden pattern.
- How does the importer authenticate against Firefly III?
- It talks to the Firefly III REST API v1 using a Personal Access Token or an OAuth client. You configure the Firefly III base URL and credentials, then trigger imports from the guided web interface or the CLI. The importer behaves as a write-only adapter that pushes accounts, transactions, and metadata into your ledger.
- Can it import CSV bank statements, and how does column mapping work?
- Yes, CSV files and CAMT.053 bank exports are first-class, low-risk connectors. Column mapping is configurable per import so you can map source fields onto canonical Firefly III fields and preview the result before committing. CSV layout drift is the main operational risk, so assign a clear owner for per-bank configuration changes.
- Which bank connectors are supported besides CSV, such as GoCardless or SimpleFIN?
- File-based connectors like CSV and CAMT.053 sit in the core flow. Aggregator connectors such as GoCardless/Nordigen, SimpleFIN, and Spectre are third-party integrations that bring consent renewal cadence, per-connection pricing, and a data-sharing review. Treat each of those as a separate integration project rather than a checkbox feature of the importer.
- What license does firefly-iii/data-importer use, and is AGPL-3.0 a problem for commercial or SaaS use?
- It is licensed AGPL-3.0, including the network clause. Unmodified internal operation is generally low risk, but modifying it and hosting it for third parties obligates source disclosure. Any commercial embedding, white-labelling, or SaaS offering needs legal sign-off before engineering starts.
- How does duplicate detection work, and can I do a dry run before committing an import?
- The importer includes duplicate detection plus a dry-run and preview flow so you can inspect mapped rows before anything is written to Firefly III. Your duplicate and reconciliation policy is still yours to define, especially when backfilling history alongside live data. Plan a rollback story for imports that land partially.
- Can I run imports unattended with cron, and does it require a queue worker?
- Unattended runs are supported by triggering the CLI from cron, with a queue worker processing the actual import jobs. Automation must target the CLI and documented API surfaces, never scraping rendered HTML, because internal endpoints and UI markup can change between releases. There is no stability contract on internal behaviour.
- Is the Firefly III Data Importer production-ready and well maintained, or should I look at alternatives?
- It is a healthy single-maintainer open source project, not an enterprise-supported dependency, and its roadmap is community-paced with no stability contract. Version coupling between the importer and the Firefly III API is the single most likely outage cause, and it fails at import time rather than deploy time. If you need vendor support or an SLA, treat it as reference architecture and budget to own the operational risk yourself.
Weaver
How can I help you explore Laravel packages today?