Accounts

Create new account.

POST
https://firefly.example.com/api/v1/accounts

Creates a new account. The data required can be submitted as a JSON body or as a list of parameters (in key=value pairs, like a webform).

Body

JSON array with the necessary account information or key=value pairs. See the model for the exact specifications.

application/json,application/x-www-form-urlencodedAccountStore
namestringrequired
Example
My checking account
typeShortAccountTypePropertyassetexpenseimportrevenuecashliabilityliabilitiesinitial-balancereconciliationrequired

Can only be one one these account types. import, initial-balance and reconciliation cannot be set manually.

Example
asset
ibanstring<iban> | null
Example
GB98MIDL07009312345678
bicstring | null
Example
BOFAUS3N
account_numberstring | null
Example
7009312345678
opening_balancestring<amount>

Represents the opening balance, the initial amount this account holds.

Example
-1012.12
opening_balance_datestring<date-time> | null

Represents the date of the opening balance.

Example
2026-10-01T00:00:00+00:00
virtual_balancestring<amount>
Example
123.45
currency_idstring

Use either currency_id or currency_code. Defaults to the user's financial administration's currency.

Example
12
currency_codestring

Use either currency_id or currency_code. Defaults to the user's financial administration's currency.

Example
EUR
activebooleantrue

If omitted, defaults to true.

Example
false
orderinteger<int32>

Order of the account

Example
1
include_net_worthbooleantrue

If omitted, defaults to true.

Example
true
account_roleAccountRoleProperty | nulldefaultAssetsharedAssetsavingAssetccAssetcashWalletAssetnull

Is only mandatory when the type is asset.

Example
defaultAsset
credit_card_typeCreditCardTypeProperty | nullmonthlyFullnull

Mandatory when the account_role is ccAsset. Can only be monthlyFull or null.

Example
monthlyFull
monthly_payment_datestring<date-time> | null

Mandatory when the account_role is ccAsset. Moment at which CC payment installments are asked for by the bank.

Example
2026-10-01T00:00:00+00:00
liability_typeLiabilityTypeProperty | nullloandebtmortgagenull

Mandatory when type is liability. Specifies the exact type.

Example
loan
liability_directionLiabilityDirectionProperty | nullcreditdebitnull

'credit' indicates somebody owes you the liability. 'debit' Indicates you owe this debt yourself. Works only for liabilities.

Example
credit
intereststring | null0

Mandatory when type is liability. Interest percentage.

Example
5.3
interest_periodInterestPeriodProperty | nulldailyweeklymonthlyquarterlyhalf-yearyearlynull

Mandatory when type is liability. Period over which the interest is calculated.

Example
monthly
notesstring | null
Example
Some example notes
latitudenumber<double> | null

Latitude of the accounts's location, if applicable. Can be used to draw a map.

Example
51.983333
longitudenumber<double> | null

Latitude of the accounts's location, if applicable. Can be used to draw a map.

Example
5.916667
zoom_levelinteger<int32> | null

Zoom level for the map, if drawn. This to set the box right. Unfortunately this is a proprietary value because each map provider has different zoom levels.

Example
6

Parameters

X-Trace-Idstring<uuid>header

Unique identifier associated with this request.

Response

200OKAccountSingle

New account stored, result in response.

Response fields application/vnd.api+json
dataAccountReadrequired
Show child attributes
typestringrequired

Immutable value

Example
accounts
idstringrequired
Example
2
attributesAccountPropertiesrequired
Show child attributes
created_atstring<date-time>read only
Example
2026-10-01T00:00:00+00:00
updated_atstring<date-time>read only
Example
2026-10-01T00:00:00+00:00
activebooleantrue
Example
false
orderinteger<int32> | null

Order of the account. Is NULL if account is not asset or liability.

Example
1
namestringrequired
Example
My checking account
typeShortAccountTypePropertyassetexpenseimportrevenuecashliabilityliabilitiesinitial-balancereconciliationrequired

Can only be one one these account types. import, initial-balance and reconciliation cannot be set manually.

Example
asset
account_roleAccountRoleProperty | nulldefaultAssetsharedAssetsavingAssetccAssetcashWalletAssetnull

Is only mandatory when the type is asset.

Example
defaultAsset
object_group_idstring | null

The group ID of the group this object is part of. NULL if no group.

Example
5
object_group_orderinteger<int32> | nullread only

The order of the group. At least 1, for the highest sorting.

Example
5
object_group_titlestring | null

The name of the group. NULL if no group.

Example
Example Group
object_has_currency_settingbooleanread only

Indicates whether the account has a currency setting. If false, the account uses the administration's primary currency. Asset accounts and liability accounts always have a currency setting, while expense and revenue accounts do not.

Example
true
currency_idstring

The currency ID of the currency associated with this object.

Example
5
currency_namestring

The currency name of the currency associated with this object.

Example
Euro
currency_codestring

The currency code of the currency associated with this object.

Example
EUR
currency_symbolstringread only
Example
$
currency_decimal_placesinteger<int32>read only
Example
2
primary_currency_idstringread only

The currency ID of the administration's primary currency.

Example
5
primary_currency_namestringread only

The currency name of the administration's primary currency.

Example
Euro
primary_currency_codestringread only

The currency code of the administration's primary currency.

Example
EUR
primary_currency_symbolstringread only

The currency symbol of the administration's primary currency.

Example
$
primary_currency_decimal_placesinteger<int32>read only

The currency decimal places of the administration's primary currency.

Example
2
current_balancestring<amount>read only

The current balance of the account in the account's currency. If the account has no currency, this is the balance in the administration's primary currency. Either way, the currency_* fields reflect the currency used.

Example
123.45
pc_current_balancestring<amount> | nullread only

The current balance of the account in the administration's primary currency. The primary_currency_* fields reflect the currency used. This field is NULL if the user does have 'convert to primary' set to true in their settings.

Example
123.45
balance_differencestring<amount>read only

If you submit a start AND end date, this will be the difference between those two moments.

Example
123.45
pc_balance_differencestring<amount> | nullread only

If you submit a start AND end date, this will be the difference in the currency of the account or the administration's primary currency between those two moments.

Example
123.45
opening_balancestring<amount>

Represents the opening balance, the initial amount this account holds in the currency of the account or the administration's primary currency if the account has no currency. Either way, the currency_* fields reflect the currency used.

Example
-1012.12
pc_opening_balancestring<amount>

The opening balance of the account in the administration's primary currency (pc). The primary_currency_* fields reflect the currency used. This field is NULL if the user does have 'convert to primary' set to true in their settings.

Example
-1012.12
virtual_balancestring<amount>

The virtual balance of the account in the account's currency or the administration's primary currency if the account has no currency.

Example
123.45
pc_virtual_balancestring<amount>

The virtual balance of the account in the administration's primary currency (pc). The primary_currency_* fields reflect the currency used. This field is NULL if the user does have 'convert to primary' set to true in their settings.

Example
123.45
debt_amountstring<amount> | null

In liability accounts (loans, debts and mortgages), this is the amount of debt in the account's currency (see the currency_* fields). In asset accounts, this is NULL.

Example
1012.12
pc_debt_amountstring<amount> | null

In liability accounts (loans, debts and mortgages), this is the amount of debt in the administration's primary currency (see the currency_* fields. In asset accounts, this is NULL.

Example
1012.12
current_balance_datestring<date-time>read only

The timestamp for this date is always 23:59:59, to indicate it's the balance at the very END of that particular day.

Example
2026-10-31T23:59:59+00:00
notesstring | null
Example
Some example notes
monthly_payment_datestring<date-time> | null

Mandatory when the account_role is ccAsset. Moment at which CC payment installments are asked for by the bank.

Example
2026-10-01T00:00:00+00:00
credit_card_typeCreditCardTypeProperty | nullmonthlyFullnull

Mandatory when the account_role is ccAsset. Can only be monthlyFull or null.

Example
monthlyFull
account_numberstring | null
Example
7009312345678
ibanstring<iban> | null
Example
GB98MIDL07009312345678
bicstring | null
Example
BOFAUS3N
opening_balance_datestring<date-time> | null

Represents the date of the opening balance.

Example
2026-10-01T00:00:00+00:00
liability_typeLiabilityTypeProperty | nullloandebtmortgagenull

Mandatory when type is liability. Specifies the exact type.

Example
loan
liability_directionLiabilityDirectionProperty | nullcreditdebitnull

'credit' indicates somebody owes you the liability. 'debit' Indicates you owe this debt yourself. Works only for liabilities.

Example
credit
intereststring | null

Mandatory when type is liability. Interest percentage.

Example
5.3
interest_periodInterestPeriodProperty | nulldailyweeklymonthlyquarterlyhalf-yearyearlynull

Mandatory when type is liability. Period over which the interest is calculated.

Example
monthly
include_net_worthbooleantrue
Example
true
longitudenumber<double> | null

Latitude of the accounts's location, if applicable. Can be used to draw a map.

Example
5.916667
latitudenumber<double> | null

Latitude of the accounts's location, if applicable. Can be used to draw a map.

Example
51.983333
zoom_levelinteger<int32> | null

Zoom level for the map, if drawn. This to set the box right. Unfortunately this is a proprietary value because each map provider has different zoom levels.

Example
6
last_activitystring<date-time> | null

Last activity of the account.

Example
2026-10-01T00:00:00+00:00
400Bad RequestBadRequestResponse

Bad request

Response fields application/json
messagestring
Example
Bad Request
exceptionstring
Example
BadRequestHttpException
401UnauthorizedUnauthenticatedResponse

Unauthenticated

Response fields application/json
messagestring
Example
Unauthenticated
exceptionstring
Example
AuthenticationException
404Not FoundNotFoundResponse

Page not found

Response fields application/json
messagestring
Example
Resource not found
exceptionstring
Example
NotFoundHttpException
422Unprocessable EntityValidationErrorResponse

Validation error. The body will have the exact details.

Response fields application/json
messagestring
Example
The given data was invalid.
errorsobject
Show child attributes
emailArray<string>
forceArray<string>
blockedArray<string>
fieldArray<string>
roleArray<string>
blocked_codeArray<string>
nameArray<string>
typeArray<string>
ibanArray<string>
startArray<string>
endArray<string>
dateArray<string>
500Internal Server ErrorInternalExceptionResponse

Internal exception

Response fields application/json
messagestring
Example
Internal Exception
exceptionstring
Example
InternalException

Authorization

firefly_iii_authoauth2

OAuth2 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.

local_bearer_authhttp (bearer)

A Personal Access Token, sent as a bearer token. Create one on your installation under Options > Profile > OAuth > Personal Access Tokens.

© James Cole, licensed under Attribution-ShareAlike 4.0 International.Docs by Sourcey
↑↓ navigate↵ selectesc close