Piggy banks

List all accounts linked to a piggy bank.

GET

https://firefly.example.com/api/v1/piggy-banks/{id}/accounts

List all accounts linked to a piggy bank. A piggy bank can be linked to multiple accounts.

curl -X GET 'https://firefly.example.com/api/v1/piggy-banks/123/accounts' \
  -H 'X-Trace-Id: 40c71bbb-c676-4f24-83cf-cc725d7d7a00' \
  -H 'Authorization: Bearer YOUR_TOKEN'

const response = await fetch('https://firefly.example.com/api/v1/piggy-banks/123/accounts', {
  method: 'GET',
  headers: {
    'X-Trace-Id': '40c71bbb-c676-4f24-83cf-cc725d7d7a00',
    'Authorization': 'Bearer YOUR_TOKEN',
  },
});

const data = await response.text();

import requests

response = requests.get(
    'https://firefly.example.com/api/v1/piggy-banks/123/accounts',
    headers={
        'X-Trace-Id': '40c71bbb-c676-4f24-83cf-cc725d7d7a00',
        'Authorization': 'Bearer YOUR_TOKEN',
    },
)
print(response.text)

{
  "data": [
    {
      "type": "accounts",
      "id": "2",
      "attributes": {
        "created_at": "2026-10-01T00:00:00+00:00",
        "updated_at": "2026-10-01T00:00:00+00:00",
        "active": false,
        "order": 1,
        "name": "My checking account",
        "type": "asset",
        "account_role": "defaultAsset",
        "object_group_id": "5",
        "object_group_order": 5,
        "object_group_title": "Example Group",
        "object_has_currency_setting": true,
        "currency_id": "5",
        "currency_name": "Euro",
        "currency_code": "EUR",
        "currency_symbol": "$",
        "currency_decimal_places": 2,
        "primary_currency_id": "5",
        "primary_currency_name": "Euro",
        "primary_currency_code": "EUR",
        "primary_currency_symbol": "$",
        "primary_currency_decimal_places": 2,
        "current_balance": "123.45",
        "pc_current_balance": "123.45",
        "balance_difference": "123.45",
        "pc_balance_difference": "123.45",
        "opening_balance": "-1012.12",
        "pc_opening_balance": "-1012.12",
        "virtual_balance": "123.45",
        "pc_virtual_balance": "123.45",
        "debt_amount": "1012.12",
        "pc_debt_amount": "1012.12",
        "current_balance_date": "2026-10-31T23:59:59+00:00",
        "notes": "Some example notes",
        "monthly_payment_date": "2026-10-01T00:00:00+00:00",
        "credit_card_type": "monthlyFull",
        "account_number": "7009312345678",
        "iban": "GB98MIDL07009312345678",
        "bic": "BOFAUS3N",
        "opening_balance_date": "2026-10-01T00:00:00+00:00",
        "liability_type": "loan",
        "liability_direction": "credit",
        "interest": "5.3",
        "interest_period": "monthly",
        "include_net_worth": true,
        "longitude": 5.916667,
        "latitude": 51.983333,
        "zoom_level": 6,
        "last_activity": "2026-10-01T00:00:00+00:00"
      }
    }
  ],
  "meta": {
    "pagination": {
      "total": 3,
      "count": 20,
      "per_page": 100,
      "current_page": 1,
      "total_pages": 1
    }
  }
}

{
  "message": "Bad Request",
  "exception": "BadRequestHttpException"
}

{
  "message": "Unauthenticated",
  "exception": "AuthenticationException"
}

{
  "message": "Resource not found",
  "exception": "NotFoundHttpException"
}

{
  "message": "Internal Exception",
  "exception": "InternalException"
}

Parameters

limitinteger<int32>query

Number of items per page. The default pagination is per 50 items.

pageinteger<int32>query

Page number. The default pagination is per 50 items.

idstringrequiredpath

The ID of the piggy bank.

Response

200OKAccountArray

A list of accounts

Response fields application/vnd.api+json

dataArray<AccountRead>required

Show child attributes

typestringrequired

Immutable value

Example

accounts

idstringrequired

Example

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

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

object_group_orderinteger<int32> | nullread only

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

Example

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

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

primary_currency_idstringread only

The currency ID of the administration's primary currency.

Example

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

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

last_activitystring<date-time> | null

Last activity of the account.

Example

2026-10-01T00:00:00+00:00

metaMetarequired

Show child attributes

paginationobject

Show child attributes

totalinteger

Example

countinteger

Example

per_pageinteger

Example

current_pageinteger

Example

total_pagesinteger

Example

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

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.