Exchange rates

Store new currency exchange rates under this date

POST

https://firefly.example.com/api/v1/exchange-rates/by-date/{date}

Stores a new set of exchange rates. The date is fixed (in the URL parameter) and the data required can be submitted as a JSON body.

curl -X POST 'https://firefly.example.com/api/v1/exchange-rates/by-date/2026-10-01' \
  -H 'X-Trace-Id: 40c71bbb-c676-4f24-83cf-cc725d7d7a00' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  --data-raw '{
  "from": "EUR",
  "rates": {
    "USD": "1.2345",
    "GBP": "6.3456"
  }
}'

const body = `{
  "from": "EUR",
  "rates": {
    "USD": "1.2345",
    "GBP": "6.3456"
  }
}`;

const response = await fetch('https://firefly.example.com/api/v1/exchange-rates/by-date/2026-10-01', {
  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 = '''{
  "from": "EUR",
  "rates": {
    "USD": "1.2345",
    "GBP": "6.3456"
  }
}'''

response = requests.post(
    'https://firefly.example.com/api/v1/exchange-rates/by-date/2026-10-01',
    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

{
  "from": "EUR",
  "rates": {
    "USD": "1.2345",
    "GBP": "6.3456"
  }
}

{
  "data": [
    {
      "type": "currency_exchange_rates",
      "id": "2",
      "attributes": {
        "created_at": "2026-10-01T00:00:00+00:00",
        "updated_at": "2026-10-01T00:00:00+00:00",
        "from_currency_id": "12",
        "from_currency_name": "Euro",
        "from_currency_code": "EUR",
        "from_currency_symbol": "$",
        "from_currency_decimal_places": 2,
        "to_currency_id": "12",
        "to_currency_name": "EUR",
        "to_currency_code": "EUR",
        "to_currency_symbol": "$",
        "to_currency_decimal_places": 2,
        "rate": "1.10340",
        "date": "2026-10-01T00:00:00+00:00"
      },
      "links": {
        "0": {
          "rel": "self",
          "uri": "/OBJECTS/1"
        },
        "self": "https://demo.firefly-iii.org/api/v1/OBJECTS/1"
      }
    }
  ],
  "meta": {
    "pagination": {
      "total": 3,
      "count": 20,
      "per_page": 100,
      "current_page": 1,
      "total_pages": 1
    }
  },
  "links": {
    "self": "https://demo.firefly-iii.org/api/v1/OBJECT?&page=4",
    "first": "https://demo.firefly-iii.org/api/v1/OBJECT?&page=1",
    "next": "https://demo.firefly-iii.org/api/v1/OBJECT?&page=3",
    "prev": "https://demo.firefly-iii.org/api/v1/OBJECT?&page=2",
    "last": "https://demo.firefly-iii.org/api/v1/OBJECT?&page=12"
  }
}

{
  "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

application/json

JSON array with the necessary currency exchange rate information. See the model for the exact specifications.

fromstringrequired

The 'from'-currency

Example

EUR

ratesobjectrequired

The actual entries for this data set. They 'key' value is 'to' currency. The value is the exchange rate.

Show child attributes

[key: string]string

Example

{
  "USD": "1.2345",
  "GBP": "6.3456"
}

Parameters

X-Trace-Idstring<uuid>header

Unique identifier associated with this request.

datestringrequiredpath

Response

200OKCurrencyExchangeRateArray

New exchange rates stored, result in response. If a rate already existed for any submitted entry, it will be updated.

Response fields application/vnd.api+json

dataArray<CurrencyExchangeRateRead>required

Show child attributes

typestringread only

Immutable value

Example

currency_exchange_rates

idstringread only

Example

attributesCurrencyExchangeProperties

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

from_currency_idstringread only

Base currency ID for this exchange rate entry.

Example

from_currency_namestringread only

Base currency name for this exchange rate entry.

Example

Euro

from_currency_codestringread only

Base currency code for this exchange rate entry.

Example

EUR

from_currency_symbolstringread only

Base currency symbol for this exchange rate entry.

Example

from_currency_decimal_placesinteger<int32>read only

Base currency decimal places for this exchange rate entry.

Example

to_currency_idstringread only

Destination currency ID for this exchange rate entry.

Example

to_currency_namestringread only

Destination currency name for this exchange rate entry.

Example

EUR

to_currency_codestringread only

Destination currency code for this exchange rate entry.

Example

EUR

to_currency_symbolstringread only

Destination currency symbol for this exchange rate entry.

Example

to_currency_decimal_placesinteger<int32>read only

Destination currency decimal places for this exchange rate entry.

Example

ratestringread only

The actual exchange rate. How many 'to' currency will you get for 1 'from' currency?

Example

1.10340

datestring<date-time>read only

Date and time of the exchange rate.

Example

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

linksObjectLink

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

metaMetarequired

Show child attributes

paginationobject

Show child attributes

totalinteger

Example

countinteger

Example

per_pageinteger

Example

current_pageinteger

Example

total_pagesinteger

Example

linksPageLinkrequired

Show child attributes

selfstring<uri>

Example

https://demo.firefly-iii.org/api/v1/OBJECT?&page=4

firststring<uri>

Example

https://demo.firefly-iii.org/api/v1/OBJECT?&page=1

nextstring<uri> | null

Example

https://demo.firefly-iii.org/api/v1/OBJECT?&page=3

prevstring<uri> | null

Example

https://demo.firefly-iii.org/api/v1/OBJECT?&page=2

laststring<uri>

Example

https://demo.firefly-iii.org/api/v1/OBJECT?&page=12

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.