Firefly III is one of the most capable self-hosted personal-finance managers, but its SimpleFIN path has an extra moving part: the official Data Importer. BankSync supplies supported bank data through SimpleFIN; the Data Importer claims the token, maps accounts and writes transactions through the Firefly III API.
That separation is powerful for automation and rules, but it also creates two services, two logs and a mapping configuration that should be versioned carefully without storing secrets.
Architecture before clicks
Firefly III owns accounts, transactions, rules, budgets and reports. The Data Importer owns external retrieval and import decisions. It needs access to Firefly III plus the SimpleFIN token or resulting configuration. Keep network access narrow: the importer needs Firefly’s API and the provider, not public exposure by default.
Official docs support configuration through the web interface or environment values such as SIMPLEFIN_TOKEN. For repeatable imports, save the generated JSON configuration into the importer’s configured import directory and invoke the documented automation command.
Firefly III setup
Run Firefly III and Data Importer
Use compatible current releases and confirm importer access to Firefly’s API.
Connect the bank in BankSync
Authorize the supported institution and verify account visibility.
Create a one-time SimpleFIN token
Use BankSync’s current SimpleFIN destination flow.
Choose SimpleFIN in Data Importer
Paste the token in the UI or supply the documented configuration value.
Map source to destination accounts
Match asset, liability and currency deliberately.
Preview the import
Inspect dates, descriptions, amounts and duplicate strategy before writing.
Save automation configuration
Download the JSON config, store it without public access and schedule the importer.
Mapping and opening balances
Firefly III’s account model is explicit. A checking account should normally map to an asset account; a credit card often maps to a liability. If you create a new destination with an opening balance and also import transactions covering that period, you can double-count. Choose a start date and reconcile one known statement balance.
Duplicate detection
The Data Importer has configurable duplicate behavior. Prefer stable source IDs where supported and keep the configuration consistent between manual and automated runs. Run the same recent-window configuration twice in a test environment: the second run should create no unwanted records.
Automation
Mount the importer’s JSON configuration read-only where practical, inject secrets separately and schedule with enough time for the provider’s upstream refresh. Preserve importer logs, but redact tokens and unrelated transaction descriptions before sharing them.
Firefly III verification
| Stage | What to do | Check |
|---|---|---|
| Services | Importer can reach Firefly API | No public exposure required |
| Source | SimpleFIN token claimed once | Credential stored securely |
| Account map | Asset and liability types match | Currency is correct |
| Opening balance | Defined at one date seam | No double counting |
| Duplicates | Second run is idempotent | Stable source identifiers |
| Automation | JSON config and secrets separated | Redacted logs |
Check both importer and destination.
Troubleshooting
If the importer sees no accounts, inspect provider errors and token claim status. If transactions arrive in the wrong direction, verify source sign semantics and Firefly destination account type before adding transformation rules. If duplicates appear only in automation, confirm the scheduled job uses the same saved configuration as the successful manual preview.
Power users can put the JSON config under private infrastructure-as-code versioning only after removing secrets and personal account labels.