Insight

Insight into expenses, grouped by budget.

GET

https://firefly.example.com/api/v1/insight/expense/budget

This endpoint gives a summary of the expenses made by the user, grouped by (any) budget.

curl -X GET 'https://firefly.example.com/api/v1/insight/expense/budget?start=2024-01-15&end=2024-01-15' \
  -H 'X-Trace-Id: 40c71bbb-c676-4f24-83cf-cc725d7d7a00' \
  -H 'Authorization: Bearer YOUR_TOKEN'

const response = await fetch('https://firefly.example.com/api/v1/insight/expense/budget?start=2024-01-15&end=2024-01-15', {
  method: 'GET',
  headers: {
    'X-Trace-Id': '40c71bbb-c676-4f24-83cf-cc725d7d7a00',
    'Authorization': 'Bearer YOUR_TOKEN',
  },
});

const data = await response.text();

import requests

response = requests.get(
    'https://firefly.example.com/api/v1/insight/expense/budget?start=2024-01-15&end=2024-01-15',
    headers={
        'X-Trace-Id': '40c71bbb-c676-4f24-83cf-cc725d7d7a00',
        'Authorization': 'Bearer YOUR_TOKEN',
    },
)
print(response.text)

[
  {
    "id": "123",
    "name": "Land lord",
    "difference": "-123.45",
    "difference_float": -123.45,
    "currency_id": "5",
    "currency_code": "EUR"
  }
]

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

Parameters

startstring<date>requiredquery

A date formatted YYYY-MM-DD.

endstring<date>requiredquery

A date formatted YYYY-MM-DD.

budgets[]Array<integer>query

The budgets to be included in the results.

accounts[]Array<integer>query

The accounts to be included in the results. If you include ID's of asset accounts or liabilities, only withdrawals from those asset accounts / liabilities will be included. Other account ID's will be ignored.

Response

200OKArray<InsightGroupEntry>

A list of budget and expense details. Each budget has one row per currency.

Response fields application/json

Array<InsightGroupEntry>

Show child attributes

idstring

This ID is a reference to the original object.

Example

namestring

This is the name of the object.

Example

Land lord

differencestring

The amount spent or earned between start date and end date, a number defined as a string, for this object and all asset accounts.

Example

-123.45

difference_floatnumber<double>

The amount spent or earned between start date and end date, a number as a float, for this object and all asset accounts. May have rounding errors.

Example

-123.45

currency_idstring

The currency ID of the expenses listed for this account.

Example

currency_codestring

The currency code of the expenses listed for this account.

Example

EUR

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.