Currencies

Store a new currency

POST

https://firefly.example.com/api/v1/currencies

Creates a new currency. 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/currencies' \
  -H 'X-Trace-Id: 40c71bbb-c676-4f24-83cf-cc725d7d7a00' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  --data-raw '{
  "enabled": true,
  "primary": true,
  "code": "AMS",
  "name": "Ankh-Morpork dollar",
  "symbol": "AM$",
  "decimal_places": 2
}'

const body = `{
  "enabled": true,
  "primary": true,
  "code": "AMS",
  "name": "Ankh-Morpork dollar",
  "symbol": "AM$",
  "decimal_places": 2
}`;

const response = await fetch('https://firefly.example.com/api/v1/currencies', {
  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 = '''{
  "enabled": true,
  "primary": true,
  "code": "AMS",
  "name": "Ankh-Morpork dollar",
  "symbol": "AM$",
  "decimal_places": 2
}'''

response = requests.post(
    'https://firefly.example.com/api/v1/currencies',
    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

{
  "enabled": true,
  "primary": true,
  "code": "AMS",
  "name": "Ankh-Morpork dollar",
  "symbol": "AM$",
  "decimal_places": 2
}

{
  "enabled": true,
  "primary": true,
  "code": "AMS",
  "name": "Ankh-Morpork dollar",
  "symbol": "AM$",
  "decimal_places": 2
}

{
  "data": {
    "type": "currencies",
    "id": "2",
    "attributes": {
      "created_at": "2026-10-01T00:00:00+00:00",
      "updated_at": "2026-10-01T00:00:00+00:00",
      "enabled": true,
      "primary": false,
      "code": "AMS",
      "name": "Ankh-Morpork dollar",
      "symbol": "AM$",
      "decimal_places": 2
    }
  }
}

{
  "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 currency information. See the model for the exact specifications.

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

enabledbooleantrue

Defaults to true

Example

true

primaryboolean

Make this currency the primary currency for the current administration. You can set this value to FALSE, in which case nothing will change to the primary currency. If you set it to TRUE, the current primary currency will no longer be the primary currency.

Example

true

codestringrequired

Example

AMS

namestringrequired

Example

Ankh-Morpork dollar

symbolstringrequired

Example

AM$

decimal_placesinteger<int32>

Supports 0-16 decimals.

Example

Parameters

X-Trace-Idstring<uuid>header

Unique identifier associated with this request.

Response

200OKCurrencySingle

New currency stored, result in response.

Response fields application/vnd.api+json

dataCurrencyReadrequired

Show child attributes

typestringrequired

Immutable value

Example

currencies

idstringrequired

Example

attributesCurrencyPropertiesrequired

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

enabledbooleantrue

Defaults to true

Example

true

primaryboolean

Is the primary currency?

Example

false

codestringrequired

Example

AMS

namestringrequired

Example

Ankh-Morpork dollar

symbolstringrequired

Example

AM$

decimal_placesinteger<int32>

Supports 0-16 decimals.

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

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.