Piggy Banks API - Firefly III

Overview

The Piggy Banks API allows you to create and manage savings goals. Piggy banks help you save for specific targets by setting aside money from your accounts and tracking your progress.

List All Piggy Banks

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

Endpoint: GET /v1/piggy-banks

Query Parameters

page

integer

Page number for pagination

Response Fields

string

Piggy bank ID

created_at

string

ISO 8601 timestamp of creation

updated_at

string

ISO 8601 timestamp of last update

name

string

Piggy bank name

percentage

integer

Percentage of target achieved (0-100+)

start_date

string

Start date (ISO 8601)

target_date

string

Target completion date (ISO 8601)

order

integer

Display order

active

boolean

Always true for piggy banks

notes

string

Piggy bank notes

object_group_id

string

Object group ID if in a group

object_group_order

integer

Order within object group

object_group_title

string

Object group title

accounts

array

Array of associated accounts with their current amounts

object_has_currency_setting

boolean

Always true for piggy banks

currency_id

string

Currency ID

currency_code

string

Currency code

currency_name

string

Currency name

currency_symbol

string

Currency symbol

currency_decimal_places

integer

Decimal places for currency

target_amount

string

Target savings amount

pc_target_amount

string

Target amount in primary currency

current_amount

string

Current saved amount

pc_current_amount

string

Current amount in primary currency

left_to_save

string

Amount remaining to reach target

pc_left_to_save

string

Remaining amount in primary currency

save_per_month

string

Recommended monthly savings to reach target

pc_save_per_month

string

Monthly savings in primary currency

Create Piggy Bank

curl -X POST "https://demo.firefly-iii.org/api/v1/piggy-banks" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "New Car Fund",
    "accounts": [
      {
        "account_id": "3",
        "current_amount": "5000.00"
      }
    ],
    "target_amount": "25000.00",
    "start_date": "2024-01-01",
    "target_date": "2026-01-01",
    "transaction_currency_code": "USD",
    "notes": "Saving for a new electric vehicle"
  }'

Endpoint: POST /v1/piggy-banks

Request Body

name

string

required

Piggy bank name (1-255 characters, must be unique)

accounts

array

required

Array of account objects (minimum 1 account)

accounts[].account_id

integer

required

Account ID (must be asset or liability account belonging to user)

accounts[].current_amount

string

Current amount saved in this account (zero or positive number)

target_amount

string

required

Target savings amount (must be ≥ sum of current amounts)

start_date

string

required

Start date (YYYY-MM-DD, after 1970-01-01, before 2038-01-17)

target_date

string

Target completion date (must be after start_date)

transaction_currency_id

integer

Currency ID (required without transaction_currency_code)

transaction_currency_code

string

Currency code (required without transaction_currency_id)

order

integer

Display order

notes

string

Piggy bank notes (max 65,000 characters)

object_group_id

integer

Object group ID to associate with

object_group_title

string

Object group title (1-255 characters)

Account Currency Validation:The currency of the piggy bank must match the currency of the associated accounts, unless the account has multi-currency support enabled.

Current Amount Limitation:The sum of all current amounts across accounts cannot exceed the target amount. Ensure your target is realistic for the initial amounts you’re setting.

Get Piggy Bank by ID

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

Endpoint: GET /v1/piggy-banks/{id} Returns the same response fields as the List endpoint.

Update Piggy Bank

curl -X PUT "https://demo.firefly-iii.org/api/v1/piggy-banks/{id}" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Electric Car Fund",
    "target_amount": "30000.00",
    "target_date": "2026-06-01",
    "notes": "Increased target for better model"
  }'

Endpoint: PUT /v1/piggy-banks/{id} Accepts the same parameters as Create Piggy Bank. All fields are optional.

Delete Piggy Bank

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

Endpoint: DELETE /v1/piggy-banks/{id} Deletes the piggy bank. The actual money in the accounts remains unchanged.

Deleting a piggy bank only removes the savings goal tracking. Your actual account balances are not affected.

Get Piggy Bank Events

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

Endpoint: GET /v1/piggy-banks/{id}/events Returns all events (additions and removals) for this piggy bank.

Query Parameters

page

integer

Page number for pagination

Get Piggy Bank Attachments

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

Endpoint: GET /v1/piggy-banks/{id}/attachments Returns all attachments for this piggy bank.

Get Piggy Bank Accounts

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

Endpoint: GET /v1/piggy-banks/{id}/accounts Returns all accounts associated with this piggy bank.

Best Practices

Setting Realistic Goals

Calculate monthly savings: Divide target by months available
Consider your budget: Ensure the goal fits within your budget constraints
Set milestone dates: Use target_date to create urgency and track progress

Managing Multiple Accounts

Piggy banks support multiple accounts, useful for:

Diversification: Spread savings across checking and savings accounts
Joint goals: Track contributions from multiple account holders
Currency hedging: Save in different currencies (with multi-currency accounts)

Tracking Progress

Use the percentage field to:

Visualize goal completion
Celebrate milestones (25%, 50%, 75%, 100%)
Adjust savings rate if behind schedule

Use the save_per_month field to:

Understand required monthly contributions
Adjust timeline if monthly amount is too high
Plan budget allocations

Common Savings Goals

Emergency Fund: 3-6 months of expenses
Major Purchases: Car, home down payment, electronics
Vacation: Holiday or travel expenses
Education: Tuition, courses, certifications
Debt Payoff: Credit card, loan principal
Investment: Initial investment capital

​Overview

​List All Piggy Banks

​Query Parameters

​Response Fields

​Create Piggy Bank

​Request Body

​Get Piggy Bank by ID

​Update Piggy Bank

​Delete Piggy Bank

​Related Endpoints

​Get Piggy Bank Events

​Query Parameters

​Get Piggy Bank Attachments

​Get Piggy Bank Accounts

​Best Practices

​Setting Realistic Goals

​Managing Multiple Accounts

​Tracking Progress

​Common Savings Goals

Overview

List All Piggy Banks

Query Parameters

Response Fields

Create Piggy Bank

Request Body

Get Piggy Bank by ID

Update Piggy Bank

Delete Piggy Bank

Related Endpoints

Get Piggy Bank Events

Query Parameters

Get Piggy Bank Attachments

Get Piggy Bank Accounts

Best Practices

Setting Realistic Goals

Managing Multiple Accounts

Tracking Progress

Common Savings Goals