Firefly III Data Importer: pulling transactions into a self-hosted ledger

Why the importer is a separate application

Firefly III is a self-hosted manager for personal finances that keeps track of expenses and income. The Data Importer exists because pulling data out of a bank and into that ledger is a problem with a different risk profile from keeping the ledger itself.

The project states the reason directly: the importer is separated from Firefly III for security and maintenance reasons. That separation is the architectural decision that defines the whole tool. A self-hosted finance application is something many people are willing to expose to the internet, and it holds the full history of their money. A component that talks to third party banking APIs, and that must hold credentials for those APIs, is a different kind of risk. Splitting it means the credential-bearing half can live on a machine that never faces the internet, while the Firefly III instance only receives a personal access token over its API.

The second reason, maintenance, matters just as much. Banking APIs and data formats change on their own schedule, independent of the core application. Keeping that churn in a separate codebase means an upstream API change does not force a release of the main application.

The audience is described with unusual precision. The importer is for people who want to track their finances and keep an eye on their money without having to upload their financial records to the cloud. You need to be a bit tech savvy, you like open source software, and you do not mind tinkering with self-hosted servers. That is a short list, and it is the same list that runs Firefly III itself.

Third party providers, or your own files

The importer does not connect to your bank directly. Instead it uses third party data providers, and the documentation notes that some of these providers are free of charge while others charge money. The topic tags on the repository name several of them, including GoCardless, Nordigen, Salt Edge and Spectre, which is a reasonable map of the aggregator and banking API services the tool has grown to cover.

That is the design choice with real consequences. Going through a provider means your transactions pass through a third party's systems, which is precisely what a privacy conscious self-hosted user was trying to avoid. It also means a cost, and a dependency on a commercial relationship you do not control. The importer is a privacy improvement relative to a closed finance app, but not a zero third party solution.

The alternative path is file based import, and the supported formats are CSV, CAMT.052 and CAMT.053. CAMT is the ISO 20022 cash management and account reporting schema, and the two variants are the debit and credit variants of it, so a European or ISO format bank export can be ingested without an aggregator. The README notes that other formats are on the to do list, which is a candid way of saying the format coverage is not complete.

Either way, the importer can be run once for a bulk import or run regularly to keep up with new transactions, so it fits both a migration from another finance tool and a recurring sync.

How the connection to Firefly III is configured

The .env.example file shows the three settings that matter, and its comments are more informative than the setting names. The Firefly III URL must include http:// or https://, must not have a trailing slash, and in a Docker setup should point at the internal IP of your Firefly III installation:

FIREFLY_III_URL=

The vanity URL is a separate setting for when your Firefly III instance is reachable internally at one address but should be linked back to at a public one. The comment gives the case explicitly, an internal address such as http://172.16.0.2:8082 alongside a public URL, and the rule is that if you set the vanity URL you must also set the Firefly III URL. It exists so that links the importer writes back into Firefly III point somewhere the user can actually click.

The third setting is the credential, and the warnings on it are worth reading twice:

FIREFLY_III_ACCESS_TOKEN=

It is a Personal Access Token in OAuth form, created on the profile and tokens page under the Remote access and tokens heading. The file tells you two things not to do. Do not use the command line token, because that is the wrong one. And do not use the APP_KEY value from your Firefly III installation, which is also the wrong one. This is a security note in a configuration file, and it is there because a wrong credential either fails confusingly or, worse, grants too much.

All three variables can also be set from a file by appending _FILE to the name, which is the pattern that lets you mount secrets in a container without writing them into an environment file.

Two ways to drive the import, and why that matters for automation

The feature list names four things: importing from many banks using third party providers, importing over the command line for easy automation, importing over an API for easy automation, and using rules and data mapping for transaction clarity.

The command line path is what makes this tool different from a button in a web interface. A scheduled import on your own cron schedule, with the source files already on disk, is a job you can run without anyone logging in. For a self-hosted finance setup, that is the difference between a system that works and a system you have to remember to visit.

The API path exists for the same reason from the other direction. If your own tools, scripts or monitoring want to trigger or inspect an import, they can do it over HTTP rather than by shelling out.

Rules and data mapping are the third piece and they address the boring reality of bank exports. A CSV from a bank has a merchant name, a memo line, a category column that says something unhelpful, and a currency that may differ from your ledger's. Rules let you say that a particular merchant string becomes a particular category or account, and mapping lets you decide which source column becomes which Firefly III field. Without that layer, an import produces a large set of uncategorised transactions that you still have to clean by hand, which defeats the purpose.

The documentation is where the specifics live, and it is linked from every section of the README, which is a reasonable pattern for a tool that has a lot of configuration surface.

What runs the import, and what the repository looks like

The repository is a Laravel application. The top level has the usual Laravel markers, an artisan file, bootstrap, config, database, public, resources, routes, storage and tests directories, plus server.php at the root, which is the standard entry point for a PHP application served outside the framework's own routing.

The dependency picture is split across two ecosystems. composer.json and composer.lock manage the PHP side, and the package.json declares a single workspace at resources/js/v2, with esbuild and eslint as the dev dependencies and patch-package as a runtime dependency. The separate JavaScript workspace is where the v2 interface is built, and the patch-package dependency means the build applies patches to node modules after install, which is how the project carries local modifications to third party frontend code.

There is also a .env.example, a .ci directory, a phpunit.xml for the PHP test suite, an eslint.config.mjs for the JavaScript lint rules, a mago.toml at the root, and a changelog.md. The .editorconfig and .gitattributes files indicate a project with some attention to consistent formatting across a mixed toolchain.

The documentation is the real installation guide. The README points at docs.firefly-iii.org for the getting started instructions, and it does not give the install commands itself, so the sensible order is to read the documentation, set the three environment variables, and then drive the import from the command line or the API.

Maintenance, licensing and the limits of the design

The project is busy. The repository is not archived, the last push was on 2026-10-18, and there is a development release named develop-20261018.1 dated the same day, on top of the tagged releases v2.3.5 from 2026-09-23 and v2.3.4 from 2026-06-30. The daily dated development builds are a pattern worth noting, because they mean a fresh build is usually available even between tagged releases.

The licence is the GNU Affero General Public License v3, and the README links the LICENSE file and the AGPL text directly. AGPL is the strongest of the common copyleft licences, and the network use clause is the part that matters here. If you modify the importer and let users interact with it over a network, you owe those users the source of your modified version. For a self-hosted tool run by one person on their own server, that is not a practical constraint. For anyone considering building a hosted service on top of the importer, it is a significant one, and it deserves a reading of the licence rather than an assumption.

The limits of the design are worth stating plainly. The importer only writes into Firefly III, so it is useless without Firefly III itself, and it does not replace a finance manager. It does not connect to banks directly, so the provider layer is both a dependency and a privacy trade. It supports three file formats and the README says more are on the list, so coverage of exotic exports is incomplete. And the recurring cost of a provider subscription, for the providers that charge, is a running cost that a self-hosted setup was probably chosen to avoid.

The project is also candid about being one person's side project. The README notes that Firefly III is a side gig, offers sponsorship links, and states that issues are collected centrally in the Firefly III repository rather than in the importer repository, which is worth knowing before you file one.

Editorial conclusion

Adopt the Firefly III Data Importer if you run Firefly III yourself and want bank transactions imported without exporting files to a hosted service, especially if you need CSV or CAMT support or a scripted import. Do not adopt it as a standalone finance manager, since it only writes into Firefly III, and skip it if you expect a free connection to your bank, because the providers it relies on range from free to paid. Verify first that FIREFLY_III_URL and FIREFLY_III_ACCESS_TOKEN point at your instance, that you created a Personal Access Token rather than a command line token, and that the provider you intend to use is both supported and acceptable to you at its own price.

Frequently asked questions

Official sources

1. firefly-iii/data-importer on GitHub
2. License: AGPL-3.0
3. Project website
4. README
5. Releases