Firefly III

Overview

Open Accountant can pull transactions directly from a self-hosted Firefly III instance via its REST API, bypassing the need to export and import CSV files manually.

Setup

Generate a Personal Access Token in your Firefly III instance under Options > Profile > OAuth, then set both values in .env:

FIREFLY_API_URL=https://firefly.example.com
FIREFLY_API_TOKEN=eyJ0eXAiOiJKV1Qi...

FIREFLY_API_URL should be the root URL of your instance (no trailing slash, no /api/v1).

Usage

Auto-Sync

wilson --sync

Syncs all configured integrations including Firefly III. Runs without the interactive agent — ideal for cron jobs. See --sync docs for details.

Interactive Mode

Sync my transactions from Firefly III

Import the last 3 months from Firefly

Headless Mode

wilson --run "Sync transactions from Firefly III"

Options

Parameter	Default	Description
`startDate`	—	Start date filter (YYYY-MM-DD)
`endDate`	—	End date filter (YYYY-MM-DD)
`limit`	all	Maximum number of transactions to fetch
`includeTransfers`	`false`	Include transfer transactions

How It Works

Open Accountant authenticates with Firefly III using your Personal Access Token
Fetches transactions via the /api/v1/transactions endpoint, paginating automatically
Maps Firefly III’s data model to Open Accountant’s schema:
- Withdrawals become negative amounts (expenses)
- Deposits become positive amounts (income)
- Transfers are skipped by default (use includeTransfers to include them)
- Reconciliation and opening balance entries are always skipped
Deduplicates by transaction_journal_id to prevent re-importing existing transactions
Preserves categories, tags, notes, and recurring bill/subscription flags

Data Mapping

Firefly III Field	Open Accountant Field	Notes
`amount` + `type`	`amount`	Withdrawal = negative, deposit = positive
`destination_name`	`description`	For withdrawals (merchant name)
`source_name`	`description`	For deposits (payer name)
`category_name`	`category`	Preserved as-is
`tags`	`tags`	Joined as comma-separated string
`bill_name` / `subscription_name`	`is_recurring`	Either present = recurring
`transaction_journal_id`	`external_id`	Prefixed with `firefly:` for dedup
`notes`	`notes`	Preserved as-is

Split Transactions

Firefly III supports split transactions — a single group containing multiple splits (e.g., a receipt with office supplies and snacks). Each split is imported as a separate transaction with its own transaction_journal_id.

Limitations

Network access required — Your Firefly III instance must be reachable from the machine running Open Accountant.
API v1 only — Uses the stable v1 API. Future API changes may require updates.
Personal Access Token in .env — Your token is stored locally in plaintext. Consider using environment variable management tools for added security.