Exchange rates

Store new currency exchange rates under this from/to pair.

POST

https://firefly.example.com/api/v1/exchange-rates/by-currencies/{from}/{to}

Stores a new set of exchange rates for this pair. The date is variable, and the data required can be submitted as a JSON body.

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

const body = `{
  "2025-08-01": "1.2345",
  "2025-08-02": "6.3456"
}`;

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

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

{
  "2025-08-01": "1.2345",
  "2025-08-02": "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.

The actual entries for this data set. They 'key' value is the date in YYYY-MM-DD. The value is the exchange rate.

[key: string]string

Example

{
  "2025-08-01": "1.2345",
  "2025-08-02": "6.3456"
}

Parameters

X-Trace-Idstring<uuid>header

Unique identifier associated with this request.

fromstringrequiredpath

The currency code of the 'from' currency.

tostringrequiredpath

The currency code of the 'to' currency.

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.