Piggy banks

Store a new piggy bank

POST

https://firefly.example.com/api/v1/piggy-banks

Creates a new piggy bank. The data required can be submitted as a JSON body or as a list of parameters.

curl -X POST 'https://firefly.example.com/api/v1/piggy-banks' \
  -H 'X-Trace-Id: 40c71bbb-c676-4f24-83cf-cc725d7d7a00' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  --data-raw '{
  "name": "New digital camera",
  "accounts": [
    {
      "id": "3",
      "name": "Checking account",
      "current_amount": "123.45"
    }
  ],
  "target_amount": "123.45",
  "current_amount": "123.45",
  "start_date": "2026-10-01",
  "target_date": "2026-10-31",
  "order": 5,
  "notes": "Some notes",
  "object_group_id": "5",
  "object_group_title": "Example Group"
}'

const body = `{
  "name": "New digital camera",
  "accounts": [
    {
      "id": "3",
      "name": "Checking account",
      "current_amount": "123.45"
    }
  ],
  "target_amount": "123.45",
  "current_amount": "123.45",
  "start_date": "2026-10-01",
  "target_date": "2026-10-31",
  "order": 5,
  "notes": "Some notes",
  "object_group_id": "5",
  "object_group_title": "Example Group"
}`;

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

const data = await response.text();

import requests

body = '''{
  "name": "New digital camera",
  "accounts": [
    {
      "id": "3",
      "name": "Checking account",
      "current_amount": "123.45"
    }
  ],
  "target_amount": "123.45",
  "current_amount": "123.45",
  "start_date": "2026-10-01",
  "target_date": "2026-10-31",
  "order": 5,
  "notes": "Some notes",
  "object_group_id": "5",
  "object_group_title": "Example Group"
}'''

response = requests.post(
    'https://firefly.example.com/api/v1/piggy-banks',
    data=body.encode('utf-8'),
    headers={
        'X-Trace-Id': '40c71bbb-c676-4f24-83cf-cc725d7d7a00',
        'Authorization': 'Bearer YOUR_TOKEN',
        'Content-Type': 'application/json',
    },
)
print(response.text)

Request Body

{
  "name": "New digital camera",
  "accounts": [
    {
      "id": "3",
      "name": "Checking account",
      "current_amount": "123.45"
    }
  ],
  "target_amount": "123.45",
  "current_amount": "123.45",
  "start_date": "2026-10-01",
  "target_date": "2026-10-31",
  "order": 5,
  "notes": "Some notes",
  "object_group_id": "5",
  "object_group_title": "Example Group"
}

{
  "name": "New digital camera",
  "accounts": [
    {
      "id": "3",
      "name": "Checking account",
      "current_amount": "123.45"
    }
  ],
  "target_amount": "123.45",
  "current_amount": "123.45",
  "start_date": "2026-10-01",
  "target_date": "2026-10-31",
  "order": 5,
  "notes": "Some notes",
  "object_group_id": "5",
  "object_group_title": "Example Group"
}

{
  "data": {
    "type": "piggy_banks",
    "id": "2",
    "attributes": {
      "created_at": "2026-10-01T00:00:00+00:00",
      "updated_at": "2026-10-01T00:00:00+00:00",
      "name": "New digital camera",
      "percentage": 12,
      "start_date": "2026-10-01T00:00:00+00:00",
      "target_date": "2026-10-01T00:00:00+00:00",
      "order": 5,
      "active": true,
      "notes": "Some notes",
      "object_group_id": "5",
      "object_group_order": 5,
      "object_group_title": "Example Group",
      "accounts": [
        {
          "account_id": "3",
          "name": "Checking account",
          "current_amount": "123.45",
          "pc_current_amount": "123.45"
        }
      ],
      "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,
      "target_amount": "123.45",
      "pc_target_amount": "123.45",
      "current_amount": "123.45",
      "pc_current_amount": "123.45",
      "left_to_save": "700.00",
      "pc_left_to_save": "700.00",
      "save_per_month": "12.45",
      "pc_save_per_month": "12.45"
    },
    "links": {
      "0": {
        "rel": "self",
        "uri": "/OBJECTS/1"
      },
      "self": "https://demo.firefly-iii.org/api/v1/OBJECTS/1"
    }
  }
}

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

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

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

{
  "message": "The given data was invalid.",
  "errors": {
    "email": [
      "string"
    ],
    "force": [
      "string"
    ],
    "blocked": [
      "string"
    ],
    "field": [
      "string"
    ],
    "role": [
      "string"
    ],
    "blocked_code": [
      "string"
    ],
    "name": [
      "string"
    ],
    "type": [
      "string"
    ],
    "iban": [
      "string"
    ],
    "start": [
      "string"
    ],
    "end": [
      "string"
    ],
    "date": [
      "string"
    ]
  }
}

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

Body

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

application/json,application/x-www-form-urlencodedPiggyBankStore

namestringrequired

Example

New digital camera

accountsArray<PiggyBankAccountStore>

Show child attributes

idstring | nullrequired

The ID of the account.

Example

namestring | null

The name of the account.

Example

Checking account

current_amountstring<amount>

The amount saved currently.

Example

123.45

target_amountstring<amount> | nullrequired

Example

123.45

current_amountstring<amount>

Example

123.45

start_datestring<date>required

The date you started with this piggy bank.

Example

2026-10-01

target_datestring<date> | null

The date you intend to finish saving money.

Example

2026-10-31

orderinteger<int32>

Example

notesstring | null

Example

Some notes

object_group_idstring | null

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

Example

object_group_titlestring | null

The name of the group. NULL if no group.

Example

Example Group

Parameters

X-Trace-Idstring<uuid>header

Unique identifier associated with this request.

Response

200OKPiggyBankSingle

New piggy bank stored, result in response.

Response fields application/vnd.api+json

dataPiggyBankReadrequired

Show child attributes

typestringrequired

Immutable value

Example

piggy_banks

idstringrequired

Example

attributesPiggyBankPropertiesrequired

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

namestringrequired

Example

New digital camera

percentageinteger<int32> | nullread only

The percentage of the target amount that has been saved, if a target amount is set.

Example

start_datestring<date-time>

The date you started with this piggy bank.

Example

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

target_datestring<date-time> | null

The date you intend to finish saving money.

Example

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

orderinteger<int32>

Example

activebooleanread only

Example

true

notesstring | null

Example

Some notes

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

accountsArray<PiggyBankAccountRead>

Show child attributes

account_idstringread only

The ID of the account.

Example

namestringread only

Example

Checking account

current_amountstring<amount>

Example

123.45

pc_current_amountstring<amount>

If convertToPrimary is on, this will show the amount in the primary currency.

Example

123.45

object_has_currency_settingbooleanread only

Indicates whether the object has a currency setting. If false, the object uses the administration's primary currency.

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

target_amountstring<amount> | nullrequired

Example

123.45

pc_target_amountstring<amount> | null

The target amount in the primary currency of the administration.

Example

123.45

current_amountstring<amount>

Example

123.45

pc_current_amountstring<amount>

The current amount in the primary currency of the administration.

Example

123.45

left_to_savestring | null

Example

700.00

pc_left_to_savestring | null

Example

700.00

save_per_monthstring | nullread only

Example

12.45

pc_save_per_monthstring | nullread only

Example

12.45

linksObjectLinkrequired

Show child attributes

0object

Show child attributes

relstring

Example

self

uristring

Example

/OBJECTS/1

selfstring<uri>

Example

https://demo.firefly-iii.org/api/v1/OBJECTS/1

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.