Firefly III API
v6.7.8Contact: james@firefly-iii.org
https://{installation}/apiYour Firefly III installationinstallation- default
firefly.example.com. Your installation's host.
https://demo.firefly-iii.org/apiFirefly III demo site (refuses command-line clients)The Firefly III REST API: every endpoint of Firefly III v6.7.8. Requests go to /api on your own installation. How to use the API shows how to create the OAuth client or Personal Access Token they need, and the API reference guide explains the currency fields, configuration values and webhooks.
Please keep in mind that the demo site does not accept requests from curl, colly, wget, etc. You must use a browser or a tool like Insomnia to make your test requests.
Please report any bugs or issues on GitHub. This file was last generated on 2026-10-19 @ 07:39:02 (Europe/Amsterdam).
Authentication
firefly_iii_authoauth2OAuth2 authorization code flow. Create a client on your installation's /profile page; it authorizes at /oauth/authorize and issues tokens at /oauth/token there. The URLs below are the demo site's. How to use the API walks through it.
- Authorization URL
https://demo.firefly-iii.org/oauth/authorize- Token URL
https://demo.firefly-iii.org/oauth/token
local_bearer_authhttpA Personal Access Token, sent as a bearer token. Create one on your installation under Options > Profile > OAuth > Personal Access Tokens.
Scheme: bearer
System
aboutThese endpoints deliver general system information, version- and meta information.
Configuration
These endpoints allow you to manage and update the Firefly III configuration. You need to have the "owner" role to update configuration.
Accounts
Endpoints that deliver all of the user's asset, expense and other accounts (and the metadata) together with related transactions, piggy banks and other objects. Also delivers endpoints for CRUD operations for accounts.
Piggy banks
piggy_banksEndpoints to control and manage all of the user's piggy banks and related objects and information.
Transactions
The most-used endpoints in Firefly III, these endpoints are used to manage the user's transactions.
- GETLists all the transaction links for an individual journal (individual split).
- GETGet a single transaction, based on one of the underlying transaction journals (transaction splits).
- DELETEDelete split from transaction
- GETLists all attachments.
- GETLists all piggy bank events.
- GETList all the user's transactions.
- POSTStore a new transaction
- GETGet a single transaction.
- PUTUpdate existing transaction
- DELETEDelete a transaction.
Transaction links
linksEndpoints to manage links between transactions, and manage the type of links available.
- GETList all transactions under this link type.
- GETList all types of links.
- POSTCreate a new link type
- GETGet single a link type.
- PUTUpdate existing link type.
- DELETEPermanently delete link type.
- GETList all transaction links.
- POSTCreate a new link between transactions
- GETGet a single link.
- PUTUpdate an existing link between transactions.
- DELETEPermanently delete link between transactions.
Attachments
Endpoints to manage the attachments of the authenticated user, including up- and downloading of the files.
Budgets
Endpoints to manage a user's budgets and get info on the related objects, like limits.
- GETList all transactions by a budget limit ID.
- GETGet all limits for a budget.
- POSTStore new budget limit.
- GETGet single budget limit.
- PUTUpdate existing budget limit.
- DELETEDelete a budget limit.
- GETGet list of budget limits by date
- GETAll transactions to a budget.
- GETLists all attachments of a budget.
- GETAll transactions without a budget.
- GETList all budgets.
- POSTStore a new budget
- GETGet a single budget.
- PUTUpdate existing budget.
- DELETEDelete a budget.
Available budgets
available_budgetsEndpoints to manage the total available amount that the user has made available to themselves. Used in periodic budgeting.
Subscriptions
billsEndpoints to manage a user's bills and all related objects.
- GETList all attachments uploaded to the bill.
- GETList all rules associated with the bill.
- GETList all transactions associated with the bill.
- GETList all bills.
- POSTStore a new bill
- GETGet a single bill.
- PUTUpdate existing bill.
- DELETEDelete a bill.
- GETList all attachments uploaded to the subscription.
- GETList all rules associated with the subscription.
- GETList all transactions associated with the subscription.
- GETList all subscriptions.
- POSTStore a new subscription
- GETGet a single subscription.
- PUTUpdate existing subscription.
- DELETEDelete a subscription.
Recurring transactions
recurrencesUse these endpoints to manage the user's recurring transactions, trigger the creation of transactions and manage the settings.
- GETList all transactions created by a recurring transaction.
- GETList all recurring transactions.
- POSTStore a new recurring transaction
- GETGet a single recurring transaction.
- PUTUpdate existing recurring transaction.
- DELETEDelete a recurring transaction.
- POSTTrigger the creation of a transaction for a specific recurring transaction
Categories
Endpoints to manage a user's categories and get information on transactions and other related objects.
Object groups
object_groupsEndpoints to control and manage all of the user's object groups. Can only be created in conjunction with another object (for example a piggy bank) and will auto-delete when no other items are linked to it.
Currencies
Endpoints to manage the currencies in Firefly III. Depending on the user's role you can also disable and enable them, or add new ones.
- GETList all accounts with this currency.
- GETList all available budgets with this currency.
- GETList all bills with this currency.
- GETList all budget limits with this currency
- GETList all recurring transactions with this currency.
- GETList all rules with this currency.
- GETList all transactions with this currency.
- GETList all exchange rates for this currency.
- GETList all currencies.
- POSTStore a new currency
- POSTEnable a single currency.
- POSTDisable a currency.
- POSTMake currency primary currency.
- GETGet a single currency.
- PUTUpdate existing currency.
- DELETEDelete a currency.
- GETGet the primary currency of the current administration.
- GETGet the default (primary) currency of the current administration.
Exchange rates
currency_exchange_ratesAll currency exchange rates.
- GETList all exchange rates that Firefly III knows.
- POSTStore a new currency exchange rate.
- GETList a single specific exchange rate.
- PUTUpdate existing currency exchange rate.
- DELETEDelete a specific currency exchange rate.
- GETList all exchange rates from/to the mentioned currencies.
- DELETEDeletes ALL currency exchange rates from 'from' to 'to'.
- GETList the exchange rate for the from and to-currency on the requested date.
- PUTUpdate existing currency exchange rate.
- DELETEDelete the currency exchange rate from 'from' to 'to' on the specified date.
- POSTStore new currency exchange rates under this date
- POSTStore new currency exchange rates under this from/to pair.
Rules
These endpoints can be used to manage all of the user's rules. Also includes triggers to execute or test rules and individual triggers.
Rule groups
rule_groupsManage all of the user's groups of rules and trigger the execution of entire groups.
Webhooks
These endpoints can be used to manage the user's webhooks and triggers them if necessary.
- GETGet all the messages of a single webhook.
- GETGet a single message from a webhook.
- DELETEDelete a webhook message.
- GETGet all the failed attempts of a single webhook message.
- GETGet a single failed attempt from a single webhook message.
- DELETEDelete a webhook attempt.
- POSTSubmit messages for a webhook.
- POSTTrigger webhook for a given transaction.
- GETList all webhooks.
- POSTStore a new webhook
- GETGet a single webhook.
- PUTUpdate existing webhook.
- DELETEDelete a webhook.
Insight
The "insight" endpoints try to deliver sums, balances and insightful information in the broadest sense of the word.
- GETInsight into expenses, grouped by expense account.
- GETInsight into expenses, grouped by asset account.
- GETInsight into income, grouped by revenue account.
- GETInsight into income, grouped by asset account.
- GETInsight into transfers, grouped by account.
- GETInsight into expenses, grouped by bill.
- GETInsight into expenses, without bill.
- GETInsight into expenses, grouped by budget.
- GETInsight into expenses, without budget.
- GETInsight into expenses, grouped by category.
- GETInsight into expenses, without category.
- GETInsight into income, grouped by category.
- GETInsight into income, without category.
- GETInsight into transfers, grouped by category.
- GETInsight into transfers, without category.
- GETInsight into expenses, grouped by tag.
- GETInsight into expenses, without tag.
- GETInsight into income, grouped by tag.
- GETInsight into income, without tag.
- GETInsight into transfers, grouped by tag.
- GETInsight into expenses, without tag.
- GETInsight into total expenses.
- GETInsight into total income.
- GETInsight into total transfers.
Summary
These endpoints deliver summaries, like sums, lists of numbers and other processed information. Mainly used for the main dashboard and pretty specific for Firefly III itself.
Charts
The "charts" endpoints deliver optimised data for charts and graphs.
Search
Endpoints that allow you to search through the user's financial data. Different from the autocomplete endpoints, the search accepts more advanced arguments.
Autocomplete
Auto-complete endpoints show basic information about Firefly III models, like the name and maybe some amounts. They all support a search query and can be used to autocomplete data in forms. Autocomplete return values always have a "name"-field.
- GETReturns all accounts of the user returned in a basic auto-complete array.
- GETReturns all bills of the user returned in a basic auto-complete array.
- GETReturns all budgets of the user returned in a basic auto-complete array.
- GETReturns all categories of the user returned in a basic auto-complete array.
- GETReturns all currencies of the user returned in a basic auto-complete array.
- GETReturns all object groups of the user returned in a basic auto-complete array.
- GETReturns all piggy banks of the user returned in a basic auto-complete array.
- GETReturns all recurring transactions of the user returned in a basic auto-complete array.
- GETReturns all rule groups of the user returned in a basic auto-complete array.
- GETReturns all rules of the user returned in a basic auto-complete array.
- GETReturns all subscriptions of the user returned in a basic auto-complete array.
- GETReturns all transaction types returned in a basic auto-complete array. English only.
- GETReturns all transaction descriptions of the user returned in a basic auto-complete array.
- GETReturns all transactions, complemented with meta information.
Data
The "data"-endpoints manage generic Firefly III and user-specific data.
- POSTBulk update transaction properties
- DELETEEndpoint to destroy user data
- GETExport account data from Firefly III
- GETExport bills from Firefly III
- GETExport subscriptions from Firefly III
- GETExport budgets and budget amount data from Firefly III
- GETExport category data from Firefly III
- GETExport piggy banks from Firefly III
- GETExport recurring transaction data from Firefly III
- GETExport rule groups and rule data from Firefly III
- GETExport transaction data from Firefly III
- DELETEEndpoint to purge user data
Preferences
These endpoints can be used to manage the user's preferences, including some hidden ones.
Financial administrations
user_groupsUser groups are the objects around which "financial administrations" are built.
Users
Use these endpoints to manage the users registered within Firefly III. You need to have the "owner" role to access these endpoints.
Models
- AccountArray
- AttachmentArray
- AutocompleteAccountArray
- AutocompleteBillArray
- AutocompleteBudgetArray
- AutocompleteCategoryArray
- AutocompleteCurrencyArray
- AutocompleteCurrencyCodeArray
- AutocompleteObjectGroupArray
- AutocompletePiggyArray
- AutocompletePiggyBalanceArray
- AutocompleteRecurrenceArray
- AutocompleteRuleArray
- AutocompleteRuleGroupArray
- AutocompleteTagArray
- AutocompleteTransactionArray
- AutocompleteTransactionIDArray
- AutocompleteTransactionTypeArray
- AutocompleteTransactionWithMetaArray
- AvailableBudgetArray
- BillArray
- BudgetArray
- BudgetLimitArray
- CategoryArray
- ConfigurationArray
- CurrencyArray
- CurrencyExchangeRateArray
- LinkTypeArray
- ObjectGroupArray
- PiggyBankArray
- PiggyBankEventArray
- PreferenceArray
- RecurrenceArray
- RuleArray
- RuleGroupArray
- TagArray
- TransactionArray
- TransactionLinkArray
- UserArray
- UserGroupArray
- WebhookArray
- WebhookAttemptArray
- WebhookMessageArray
- AutocompleteAccount
- AutocompleteBill
- AutocompleteBudget
- AutocompleteCategory
- AutocompleteCurrency
- AutocompleteCurrencyCode
- AutocompleteObjectGroup
- AutocompletePiggy
- AutocompletePiggyBalance
- AutocompleteRecurrence
- AutocompleteRule
- AutocompleteRuleGroup
- AutocompleteTag
- AutocompleteTransaction
- AutocompleteTransactionID
- AutocompleteTransactionType
- AutocompleteTransactionWithMeta
- ChartDataPoint
- ChartDataSet
- ChartLine
- DataDestroyObject
- AccountSearchFieldFilter
- ConfigValueFilterTitle of the configuration value.
- ConfigValueUpdateFilter
- ExportFileFilter
- InsightGroup
- InsightGroupEntry
- InsightTotal
- InsightTotalEntry
- InsightTransfer
- InsightTransferEntry
- CategoryRead
- CategorySingle
- ConfigurationSingle
- CurrencyRead
- CurrencySingle
- LinkTypeRead
- LinkTypeSingle
- ObjectGroupRead
- ObjectGroupSingle
- PiggyBankEventRead
- PiggyBankRead
- PiggyBankSingle
- PreferenceRead
- PreferenceSingle
- RecurrenceRead
- RecurrenceSingle
- RuleGroupRead
- RuleGroupSingle
- RuleRead
- RuleSingle
- TagRead
- TransactionLinkRead
- TransactionLinkSingle
- TransactionRead
- TransactionSingle
- UserRead
- WebhookAttemptRead
- WebhookAttemptSingle
- WebhookMessageRead
- WebhookMessageSingle
- WebhookRead
- WebhookSingle
- AccountProperties
- AccountRead
- AccountSingle
- AccountStore
- AccountUpdate
- ArrayEntryWithCurrencyAndSum
- AttachmentProperties
- AttachmentRead
- AttachmentSingle
- AttachmentStore
- AttachmentUpdate
- AvailableBudgetProperties
- AvailableBudgetRead
- AvailableBudgetSingle
- BillProperties
- BillRead
- BillSingle
- BillStore
- BillUpdate
- BudgetProperties
- BudgetRead
- BudgetSingle
- BudgetStore
- BudgetUpdate
- BudgetLimitProperties
- BudgetLimitRead
- BudgetLimitSingle
- BudgetLimitStore
- BudgetLimitUpdate
- CategoryProperties
- CategoryStore
- CategoryUpdate
- CurrencyExchangeProperties
- CurrencyExchangeRateRead
- CurrencyExchangeRateSingle
- CurrencyExchangeRateStore
- CurrencyExchangeRateStoreByDate
- CurrencyExchangeRateStoreByPairThe actual entries for this data set. They 'key' value is the date in YYYY-MM-DD. The value is the exchange rate.
- CurrencyExchangeRateUpdate
- CurrencyExchangeRateUpdateNoDate
- ObjectGroup
- ObjectGroupUpdate
- ObjectLink
- PageLink
- PiggyBankAccountRead
- PiggyBankAccountStore
- PiggyBankAccountUpdate
- PiggyBankProperties
- PiggyBankStore
- PiggyBankUpdate
- PiggyBankEventProperties
- Preference
- PreferenceUpdate
- RecurrenceProperties
- RecurrenceStore
- RecurrenceUpdate
- RecurrenceRepetition
- RecurrenceRepetitionStore
- RecurrenceRepetitionUpdate
- RecurrenceTransaction
- RecurrenceTransactionStore
- RecurrenceTransactionUpdate
- Rule
- RuleStore
- RuleUpdate
- RuleAction
- RuleActionStore
- RuleActionUpdate
- RuleGroup
- RuleGroupStore
- RuleGroupUpdate
- RuleTrigger
- RuleTriggerStore
- RuleTriggerUpdate
- TagModel
- TagModelStore
- TagModelUpdate
- CurrencyProperties
- CurrencyStore
- CurrencyUpdate
- Transaction
- TransactionStore
- TransactionUpdate
- TransactionLink
- TransactionLinkStore
- TransactionLinkUpdate
- LinkType
- LinkTypeUpdate
- TransactionSplit
- TransactionSplitStore
- TransactionSplitUpdate
- User
- UserGroupRead
- UserGroupReadAttributes
- UserGroupReadMembers
- UserGroupReadRoleThe possible roles of the user in this user group are documented in the [API reference guide](/references/firefly-iii/api/).
- UserGroupSingle
- UserGroupUpdate
- WebhookDeliveryFormat of the delivered response.
- WebhookDeliveryArray
- WebhookProperties
- WebhookResponseIndicator for what Firefly III will deliver to the webhook URL.
- WebhookResponseArray
- WebhookStore
- WebhookTriggerThe trigger for the webhook.
- WebhookTriggerArray
- WebhookUpdate
- WebhookAttempt
- WebhookMessage
- AttachableTypeThe object class to which the attachment must be linked.
- AutoBudgetPeriodPeriod for the auto budget
- AutoBudgetTypeThe type of auto-budget that Firefly III must create.
- BillRepeatFrequencyHow often the bill must be paid.
- PolymorphicProperty
- RecurrenceRepetitionTypeThe type of the repetition. ndom means: the n-th weekday of the month, where you can also specify which day of the week.
- RecurrenceTransactionType
- RuleActionKeywordThe type of thing this action will do. A limited set is possible.
- RuleTriggerKeywordThe type of thing this trigger responds to. A limited set is possible
- RuleTriggerTypeWhich action is necessary for the rule to fire? Use either store-journal, update-journal or manual-activation.
- StringArrayItemThe actual preference content.
- UserBlockedCodePropertyIf you say the user must be blocked, this will be the reason code.
- UserRolePropertyRole for the user. Can be empty or omitted.
- BasicSummary
- BasicSummaryEntry
- Configuration
- ConfigurationUpdate
- CronResult
- CronResultRow
- ReleaseNotes
- SystemInfo
- UserSingle
- AccountTypeFilter
- TransactionTypeFilter
- Meta
- AccountRolePropertyIs only mandatory when the type is asset.
- AccountTypeProperty
- ChartDatasetPeriodPropertyPeriod of the chart.
- CreditCardTypePropertyMandatory when the account_role is ccAsset. Can only be monthlyFull or null.
- InterestPeriodPropertyMandatory when type is liability. Period over which the interest is calculated.
- LiabilityDirectionProperty'credit' indicates somebody owes you the liability. 'debit' Indicates you owe this debt yourself. Works only for liabilities.
- LiabilityTypePropertyMandatory when type is liability. Specifies the exact type.
- ShortAccountTypePropertyCan only be one one these account types. import, initial-balance and reconciliation cannot be set manually.
- TransactionTypeProperty
- BadRequestResponse
- InternalExceptionResponse
- NotFoundResponse
- UnauthenticatedResponse
- ValidationErrorResponse
