Accounts API

Manage asset, expense, revenue, and liability accounts

Overview

The Accounts API allows you to manage all types of accounts in Firefly III, including asset accounts, expense accounts, revenue accounts, and liability accounts.

List All Accounts

cURL

curl -X GET "https://demo.firefly-iii.org/api/v1/accounts" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Accept: application/json"

Endpoint: GET /v1/accounts

Query Parameters

page · integer

Page number for pagination

type · string

Filter by account type: asset, expense, revenue, cash, liability, liabilities, initial-balance, reconciliation

Response Fields

id · string

Unique identifier for the account

created_at · string

ISO 8601 timestamp of creation

updated_at · string

ISO 8601 timestamp of last update

active · boolean

Whether the account is active

order · integer

Display order for asset and liability accounts

name · string

Account name

type · string

Account type (lowercase)

account_role · string

For asset accounts: defaultAsset, sharedAsset, savingAsset, ccAsset, or cashWalletAsset

currency_id · string

ID of the account’s currency

currency_code · string

Currency code (e.g., USD, EUR)

currency_symbol · string

Currency symbol (e.g., $, €)

currency_decimal_places · integer

Number of decimal places for the currency

current_balance · string

Current account balance

opening_balance · string

Opening balance (for asset and liability accounts)

opening_balance_date · string

Date of opening balance

virtual_balance · string

Virtual balance offset

iban · string

International Bank Account Number

bic · string

Bank Identifier Code

account_number · string

Account number

notes · string

Account notes

latitude · number

Geographic latitude

longitude · number

Geographic longitude

zoom_level · integer

Map zoom level

include_net_worth · boolean

Whether to include in net worth calculations

liability_type · string

For liabilities: loan, debt, or mortgage

liability_direction · string

For liabilities: credit or debit

interest · string

Interest rate percentage

interest_period · string

Interest calculation period

Create Account

cURL

curl -X POST "https://demo.firefly-iii.org/api/v1/accounts" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Savings Account",
    "type": "asset",
    "account_role": "savingAsset",
    "currency_code": "USD",
    "opening_balance": "1000.00",
    "opening_balance_date": "2024-01-01",
    "active": true,
    "include_net_worth": true
  }'

Endpoint: POST /v1/accounts

Request Body

name · string · required

Account name (1-1024 characters, must be unique)

type · string · required

Account type: asset, expense, revenue, cash, liability, liabilities, initial-balance, reconciliation

iban · string

Valid IBAN (must be unique for the account type)

bic · string

Valid BIC code

account_number · string

Account number (1-255 characters, must be unique for the account type)

opening_balance · string

Opening balance (required if opening_balance_date is provided)

opening_balance_date · string

Date in YYYY-MM-DD format (required if opening_balance is provided)

virtual_balance · string

Virtual balance amount

order · integer

Display order

currency_id · integer

Currency ID (must exist in transaction_currencies)

currency_code · string

3-character currency code (must exist in transaction_currencies)

active · boolean · default: "true"

Whether the account is active

include_net_worth · boolean · default: "true"

Include in net worth calculations

account_role · string

Required for asset accounts: defaultAsset, sharedAsset, savingAsset, ccAsset, or cashWalletAsset

credit_card_type · string

Required if account_role is ccAsset: monthlyFull or other credit card types

monthly_payment_date · string

Required if account_role is ccAsset: date in YYYY-MM-DD format

liability_type · string

Required if type is liability or liabilities: loan, debt, or mortgage

liability_direction · string

Required if type is liability or liabilities: credit or debit

liability_amount · string

Initial liability amount (required with liability_start_date)

liability_start_date · string

Liability start date (required with liability_amount)

interest · string

Interest rate percentage (0-100)

interest_period · string

Interest period from configured options

notes · string

Account notes (max 32,768 characters)

latitude · number

Geographic latitude

longitude · number

Geographic longitude

zoom_level · integer

Map zoom level

For asset accounts, the account_role field is required and determines how the account behaves.

For liability accounts, both liability_type and liability_direction are required.

Get Account by ID

cURL

curl -X GET "https://demo.firefly-iii.org/api/v1/accounts/{id}" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Accept: application/json"

Endpoint: GET /v1/accounts/{id}

Returns the same response fields as the List endpoint.

Update Account

cURL

curl -X PUT "https://demo.firefly-iii.org/api/v1/accounts/{id}" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Updated Savings Account",
    "active": true,
    "notes": "My primary savings account"
  }'

Endpoint: PUT /v1/accounts/{id}

Accepts the same parameters as Create Account. All fields are optional.

Delete Account

cURL

curl -X DELETE "https://demo.firefly-iii.org/api/v1/accounts/{id}" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Accept: application/json"

Endpoint: DELETE /v1/accounts/{id}

Deletes the specified account and all associated data.

Deleting an account will also delete all associated transactions. This action cannot be undone.

Related Endpoints

Get Account Piggy Banks

Endpoint: GET /v1/accounts/{id}/piggy-banks

Returns all piggy banks associated with this account.

Get Account Transactions

Endpoint: GET /v1/accounts/{id}/transactions

Returns all transactions for this account.

Get Account Attachments

Endpoint: GET /v1/accounts/{id}/attachments

Returns all attachments associated with this account.