HomeGuidesAPI Reference
Log In
Guides

Fetching your Risk Report

Suggest Edits

📘

Prerequisites

Make sure to first complete the Implementation guide!

To be able to fetch the report your need the id you received on flow initiation.

GET /rest/risk-reports/{id}

{
  "period": 12,
  "accounts": [
    {
      "name": "FlexiCash",
      "type": "Giro account",
      "owners": [
        "Max Mustermann, Erika Mustermann"
      ],
      "iban": "DE93300308800013441006",
      "currency": "EUR",
      "is_jointly_managed": true,
      "is_main_account": true,
      "last_transaction_on": "2023-01-14",
      "balance": {
        "days_in_overdraft": 0,
        "average": {
          "one_month": 1234.56,
          "three_months": 234.56,
          "six_months": 562.67
        }
      },
      "verification_result": {
        "provided": {
          "name": "Max Mustermann",
          "iban": "DE93300308800013441006"
        },
        "matched": {
          "name": "Max Mustermann",
          "affinity": "VERY_HIGH"
        }
      }
    }
  ],
  "income": {
    "regular": [
      {
        "total": 1234.56,
        "low": -220.2,
        "high": 1400.5,
        "average": 2123.25,
        "count": 14,
        "href": "https://finx-s.finleap.cloud/rest/transactions?categories=3,14&since=2020-01-01&until=2020-01-31",
        "category": {
          "id": 123,
          "name": "Online-Shopping"
        },
        "first_booked_on": "2023-01-14",
        "last_booked_on": "2023-01-14"
      }
    ],
    "variable": [
      {
        "total": 1234.56,
        "low": -220.2,
        "high": 1400.5,
        "average": 2123.25,
        "count": 14,
        "href": "https://finx-s.finleap.cloud/rest/transactions?categories=3,14&since=2020-01-01&until=2020-01-31",
        "category": {
          "id": 123,
          "name": "Online-Shopping"
        },
        "first_booked_on": "2023-01-14",
        "last_booked_on": "2023-01-14"
      }
    ],
    "primary": {
      "recurrence": "monthly",
      "stability": 0.5,
      "total": 1234.56,
      "low": -220.2,
      "high": 1400.5,
      "average": 2123.25,
      "count": 14,
      "href": "https://finx-s.finleap.cloud/rest/transactions?categories=3,14&since=2020-01-01&until=2020-01-31",
      "category": {
        "id": 123,
        "name": "Online-Shopping"
      },
      "first_booked_on": "2023-01-14",
      "last_booked_on": "2023-01-14",
      "payment_partner": {
        "id": "6702b891-b8e6-4892-8615-5440e39d3d0e",
        "name": "Some Supermarket GmbH"
      }
    },
    "closeness": 10,
    "consumption_rate": 0.5
  },
  "expenses": {
    "regular": [
      {
        "total": 1234.56,
        "low": -220.2,
        "high": 1400.5,
        "average": 2123.25,
        "count": 14,
        "href": "https://finx-s.finleap.cloud/rest/transactions?categories=3,14&since=2020-01-01&until=2020-01-31",
        "category": {
          "id": 123,
          "name": "Online-Shopping"
        },
        "first_booked_on": "2023-01-14",
        "last_booked_on": "2023-01-14",
        "ratio_to_income": 98
      }
    ],
    "variable": [
      {
        "total": 1234.56,
        "low": -220.2,
        "high": 1400.5,
        "average": 2123.25,
        "count": 14,
        "href": "https://finx-s.finleap.cloud/rest/transactions?categories=3,14&since=2020-01-01&until=2020-01-31",
        "category": {
          "id": 123,
          "name": "Online-Shopping"
        },
        "first_booked_on": "2023-01-14",
        "last_booked_on": "2023-01-14",
        "ratio_to_income": 98
      }
    ]
  },
  "atm": {
    "total": 1234.56,
    "low": -220.2,
    "high": 1400.5,
    "average": 2123.25,
    "count": 14,
    "href": "https://finx-s.finleap.cloud/rest/transactions?categories=3,14&since=2020-01-01&until=2020-01-31"
  },
  "gambling": {
    "total": 1234.56,
    "low": -220.2,
    "high": 1400.5,
    "average": 2123.25,
    "count": 14,
    "href": "https://finx-s.finleap.cloud/rest/transactions?categories=3,14&since=2020-01-01&until=2020-01-31",
    "ratio_to_income": 0
  },
  "debt_collection": {
    "total": 1234.56,
    "low": -220.2,
    "high": 1400.5,
    "average": 2123.25,
    "count": 14,
    "href": "https://finx-s.finleap.cloud/rest/transactions?categories=3,14&since=2020-01-01&until=2020-01-31"
  },
  "loan": {
    "total": 1234.56,
    "low": -220.2,
    "high": 1400.5,
    "average": 2123.25,
    "count": 14,
    "href": "https://finx-s.finleap.cloud/rest/transactions?categories=3,14&since=2020-01-01&until=2020-01-31",
    "ratio_to_income": 0
  }
}

Details

The Risk Report is broken down into several sections;

Account Specific

  1. Accounts

The Accounts section provides a detailed overview of the information for the individual accounts the user has connected;

is_main_account identifies if a primary income has been detected on the individual account.

The balanceobject includes important information about the money held in the account, identifying if and for how long an account balance was in the negative as well as an average over a certain amount of time.

The verification_result provides an evaluation of the affinity between the initially provided name and the best matching account-holder name.

The affinity is

  • VERY_HIGH if the names match 100% (case-insensitive)
  • HIGH if there is a significant overlap with only minor deviations (e.g. "Doe, John" instead of "John Doe" or "Hans Muller" instead of "Hans Müller")
  • MEDIUM if there is only some similarity between the names (e.g. "Helge Braun" vs. "Stefan Braun")
  • LOW if the names don't match at all.

Full Aggregation

📘

The sections defined below are aggregated accross all the accounts that have been connected by the user. If you want to limit this to one account only, ensure to set the allow_multi_selectionto falsein the first step of the implementation.

  1. Income

The income section breaks down into 3 sections; regular, variable and primary:

The regular object aggregates all transactions that have been identified as an incoming contract

The variable object aggregates all transactions that do not have a specific recurrence.

The primary object provides a more in-depth analysis of the users' primary income stream by additionally providing the following:

  • recurrencethe frequency at which the income stream is received.
  • stabilitythe ratio at which the income stream has been detected in the reporting_period.
  • closenessdays since the last income transaction was detected.
  • consumption rateratio of the expenses compared to the income.
  1. Expenses

The income section breaks down into 2 sections; regular and variable:

The regular object aggregates all transactions that have been identified as an outgoing contract

The variable object aggregates all transactions that do not have a specific recurrence.

  1. Indicators

The response will also return a set of aggregations for specific Indicators such as atm, loan and gambling.

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 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.

Updated 7 months ago