Authorization

In order to fetch the income report of a user, you require the access tokenthat has been obtained in the previous steps. Use the access token to make requests to the Retrieve Income Report endpoint.

Endpoint Overview

Retrieve Income Report

An income report can be fetched using the following filters provided in the query:

since - the start date of the period for which the report will be generated
until - the end date of the period for which the report will be generated
accounts - list of accounts that shall be included in the report
accesses - list of accesses that shall be included in the report

Please refer to fetch accounts on how to get the accounts and to fetch accesses on how to get available accesses of a user.

Request Example:

GET /rest/income-report?since=2023-01&until=2023-02

Response Example:

{
  "period": 0,
  "income": {
    "summary": {
      "total": 1234.56,
      "low": -220.2,
      "high": 1400.5,
      "average": 2123.25,
      "href": "https://finx-s.finleap.cloud/rest/transactions?categories=3,14&since=2020-01-01&until=2020-01-31",
      "count": 14
    },
    "streams": [
      {
        "category": {
          "id": 56,
          "name": "Online-Shopping"
        },
        "first_booked_on": "2023-01-14",
        "last_booked_on": "2023-01-14"
      }
    ],
    "primary": {
      "category": {
        "id": 56,
        "name": "Online-Shopping"
      },
      "first_booked_on": "2023-01-14",
      "last_booked_on": "2023-01-14",
      "payment_partner": "Deutsche Telekom"
    }
  },
  "regular_expenses": [
    {
      "summary": {
        "total": 1234.56,
        "low": -220.2,
        "high": 1400.5,
        "average": 2123.25,
        "href": "https://finx-s.finleap.cloud/rest/transactions?categories=3,14&since=2020-01-01&until=2020-01-31",
        "count": 14
      },
      "streams": [
        {
          "category": {
            "id": 56,
            "name": "Online-Shopping"
          },
          "first_booked_on": "2023-01-14",
          "last_booked_on": "2023-01-14"
        }
      ]
    }
  ],
  "variable_expenses": [
    {
      "summary": {
        "total": 1234.56,
        "low": -220.2,
        "high": 1400.5,
        "average": 2123.25,
        "href": "https://finx-s.finleap.cloud/rest/transactions?categories=3,14&since=2020-01-01&until=2020-01-31",
        "count": 14
      },
      "streams": [
        {
          "category": {
            "id": 56,
            "name": "Online-Shopping"
          },
          "first_booked_on": "2023-01-14",
          "last_booked_on": "2023-01-14"
        }
      ]
    }
  ],
  "disposable_income": {
    "total": 1234.56,
    "low": -220.2,
    "high": 1400.5,
    "average": 2123.25,
    "ratio": 0.32
  },
  "discretionary_income": {
    "total": 1234.56,
    "low": -220.2,
    "high": 1400.5,
    "average": 2123.25,
    "ratio": 0.32
  }
}

For detailed technical information on request parameters, response formats, and implementation specifics, please refer to our API Reference linked above.

Error Handling

The finX API employs HTTP status codes to indicate the outcome of each API request. Familiarity with these codes is essential for understanding the response.

200 OK: This status code indicates a successful request, typically returned when retrieving account or transaction data.

400 Bad Request: If the request is malformed, contains missing or invalid parameters, or violates validation rules, the API responds with a 400 status code.

401 Unauthorized: When the provided authorization is insufficient or invalid, the API responds with a 401 status code, indicating the need for proper user authentication.