Retrieve risk insights for a link

Request the risk insights for a given link ID.

If you need to know the currency of the account, just do a GET Details to the accounts endpoint (using the ID you receive from the accounts response).

📘

Getting the account currency

If you need to know the currency of the account, make a GET Details request to the Accounts endpoint (using the account ID you receive in the accounts array of the response).

🚧

Request accounts and transactions first

Before requesting risk insights, you must first make a POST Retrieve Accounts and a POST Retrieve Transactions request.

If you do not request the accounts and transactions, the analyses won't be able to be conducted.

Query Params
string

Omit certain fields from being returned in the response. For more information, see our Filtering responses DevPortal article.

string

Return only the specified fields in the response. For more information, see our Filtering responses DevPortal article.

Body Params
string
required
string

The MFA token generated by the institution which is required to continue a session.

boolean
Defaults to true

Indicates whether or not to persist the data in Belvo. By default, this is set to true and we return a 201 Created response.

When set to false, the data won't be persisted and we return a 200 OK response.

Responses

Response body
object
string
required

Belvo's unique identifier for the current item.

string | null
required
date-time
required

The ISO-8601 timestamp of when the data point was created in Belvo's database.

array of strings | null
required

An array of Belvo-generated account numbers (UUIDs) that were used during the risk insights analysis. If no accounts were found, we return an empty array.

accounts*
object | null
required

Aggregate details regarding the assets used in the risk insight analysis. For asset metrics, we only consider checking and savings accounts.

Asset metrics can provide a snapshot of your user's wealth and liquid assets, indicating how they manage their wealth and their current financial status.

array of strings | null
required

An array of institutions from which account information was retrieved for the user.

Note: For most use cases, this array will only return one item.

institutions*
int32 | null

The total number of accounts found for the user.

int32 | null
required

The total number of checking accounts found for the user.

int32 | null
required

The total number of savings accounts found for the user.

float | null
required

The total closing balance of all checking accounts.

float | null
required

The total closing balance of all savings accounts.

object | null
required

Aggregated metrics calculated based on the user's credit card accounts.

Credit card metrics illustrate a customer's credit card habits, revealing how many credit card accounts a customer has, their total credit limit, how much of that limit they're using, and the rate of their credit card limit utilization.

int32
required
≥ 0

Number of credit cards accounts associated to the user.

float | null
required

Sum total of all credit cards' limits.

float | null
required

Sum total of all credit used.

float | null
required

The percentage of the credit card limit used.

object | null
required

Aggregated metrics calculated based on the user's loan accounts and checking accounts that have an overdraft.

Loan metrics help in understanding a customer's borrowing and repayment behavior, which can help in assessing their ability to take on additional credit and potential default risks.

int32
required

The number of loan accounts associated with the user.

float | null
required

Sum total of the principal for all of the user's loan accounts.

float | null
required

Sum total of the outstanding principal for all the user's loan accounts.

float | null
required

Sum total of the monthly payments for all the user's loan accounts.

float | null
required

The percentage of the loan limit used.

float | null
required

The total overdraft limit of all checking and savings accounts.

float | null
required

The percentage of the overdraft limit used.

object | null
required

Balance metrics calculated based on the user's balances from checking and savings accounts.

float | null
required

The balance of all the accounts at the collected_at time.

float | null
required

The minimum balance in the last three days.

float | null
required

The minimum balance in the last week).

float | null
required

The minimum balance in the last month.

float | null
required

The minimum balance in the last three months.

float | null
required

The minimum balance in the six last months.

float | null
required

The minimum balance in the last twelve months.

float | null
required

The mean balance in the last three days.

float | null
required

The mean balance in the last week.

float | null
required

The mean balance in the last month.

float | null
required

The mean balance in the last three months.

float | null
required

The mean balance in the last six months.

float | null
required

The mean balance in the last twelve months.

float | null
required

The maximum balance in the last three days.

float | null
required

The maximum balance in the last week.

float | null
required

The maximum balance in the last month.

float | null
required

The maximum balance in the last three months.

float | null
required

The maximum balance in the last six months.

float | null
required

The maximum balance in the last twelve months.

float | null
required

The balance standard deviation in the last three days.

float | null
required

The balance standard deviation in the last week.

float | null
required

The balance standard deviation in the last month.

float | null
required

The balance standard deviation in the last three months.

float | null
required

The balance standard deviation in the last six months.

float | null
required

The balance standard deviation in the last twelve months.

float | null
required

The balance trend of the user in the last three days.

float | null
required

The balance trend of the user in the last week.

float | null
required

The balance trend of the user in the last month.

float | null
required

The balance trend of the user in the last three months.

float | null
required

The balance trend of the user in the last six months.

float | null
required

The balance trend of the user in the last twelve months.

int32 | null
required

The number of days that the total balance of the account is less than or equal to 0 in the last three days.

int32 | null
required

The number of days that the total balance of the account is less than or equal to 0 in the last week.

int32 | null
required

The number of days that the total balance of the account is less than or equal to 0 in the last month.

int32 | null
required

The number of days that the total balance of the account is less than or equal to 0 in the last three months.

int32 | null
required

The number of days that the total balance of the account is less than or equal to 0 in the last six months.

int32 | null
required

The number of days that the total balance of the account is less than or equal to 0 in the last twelve months.

int32 | null
required

The number of days that the mean balance of the account is less than or equal to the amount specified in mean_daily_balance_3d.

int32 | null
required

The number of days that the mean balance of the account is less than or equal to the amount specified in mean_daily_balance_1w.

int32 | null
required

The number of days that the mean balance of the account is less than or equal to the amount specified in mean_daily_balance_1m.

int32 | null
required

The number of days that the mean balance of the account is less than or equal to the amount specified in mean_daily_balance_3m.

int32 | null
required

The number of days that the mean balance of the account is less than or equal to the amount specified in mean_daily_balance_6m.

int32 | null
required

The number of days that the mean balance of the account is less than or equal to the amount specified in mean_daily_balance_12m.

int32 | null
required

The number of days that the total balance of the account is less than or equal to the amount specified in balance_threshold_x in the last three days.

int32 | null
required

The number of days that the total balance of the account is less than or equal to the amount specified in balance_threshold_x in the last week.

int32 | null
required

The number of days that the total balance of the account is less than or equal to the amount specified in balance_threshold_x in the last month.

int32 | null
required

The number of days that the total balance of the account is less than or equal to the amount specified in balance_threshold_x in the last three months.

int32 | null
required

The number of days that the total balance of the account is less than or equal to the amount specified in balance_threshold_x in the last six months.

int32 | null
required

The number of days that the total balance of the account is less than or equal to the amount specified in balance_threshold_x in the last twelve months.

float
required

The threshold used to compute days_balance_below_x_period. Please note, this is value is country specific (both in terms of the amount and the currency).

object | null
required

Aggregated metrics calculated based on the user's transactions from checking, savings, credit card, and loan accounts.

ℹ️

Note

If there is not enough transactional data for a given period, we return null for calculated fields and 0 for 'count-based' fields. For example, if the account has only been open for five days (or you have provided data just for five days), we return values for _3d, _1w, and _1m, however:

  • mean_num_transactions_3m will return null as there is no data for months two and three (calculated field).
  • num_transactions_3m will return 0 as there is no data for months two and three ('count-based' field)
int32
required
Defaults to 0

The total number of transactions analyzed to determine the risk insights for the last three days (incoming and outgoing).

int32
required
Defaults to 0

The total number of transactions analyzed to determine the risk insights for the last week (incoming and outgoing).

int32
required
Defaults to 0

The total number of transactions analyzed to determine the risk insights for the last month (incoming and outgoing).

int32
required
Defaults to 0

The total number of transactions analyzed to determine the risk insights for the last three months (incoming and outgoing).

int32
required
Defaults to 670

The total number of transactions analyzed to determine the risk insights for the last six months (incoming and outgoing).

int32
required
Defaults to 0

The total number of transactions analyzed to determine the risk insights for the last twelve months (incoming and outgoing).

int32
required
Defaults to 0

The maximum number of transactions for the last three days.

int32
required
Defaults to 0

The maximum number of transactions for the last week.

int32
required
Defaults to 0

The maximum number of transactions for the last month.

int32
required
Defaults to 0

The maximum number of transactions for the last three months.

int32
required
Defaults to 0

The maximum number of transactions for the last six months.

int32
required
Defaults to 0

The maximum number of transactions for the last twelve months.

float
required
Defaults to 0

The mean number of transactions for the last three days.

float
required
Defaults to 0

The mean number of transactions for the last week.

float
required
Defaults to 0

The mean number of transactions for the last month.

float
required
Defaults to 0

The mean number of transactions for the last three months.

float
required
Defaults to 0

The mean number of transactions for the last six months.

float
required
Defaults to 0

The mean number of transactions for the last twelve months.

int32
required
Defaults to 0

The total number of inflow transactions for the last three days.

int32
required
Defaults to 0

The total number of inflow transactions for the last week.

int32
required
Defaults to 0

The total number of inflow transactions for the last month.

int32
required
Defaults to 0

The total number of inflow transactions for the last three months.

int32
required
Defaults to 0

The total number of inflow transactions for the last six months.

int32
required
Defaults to 0

The total number of inflow transactions for the last twelve months.

int32
required
Defaults to 0

The maximum number of inflow transactions for the last three days.

int32
required
Defaults to 0

The maximum number of inflow transactions for the last week.

int32
required
Defaults to 0

The maximum number of inflow transactions for the last month.

int32
required
Defaults to 0

The maximum number of inflow transactions for the last three months.

int32
required
Defaults to 0

The maximum number of inflow transactions for the last six months.

int32
required
Defaults to 0

The maximum number of inflow transactions for the last twelve months.

float
required
Defaults to 0

The mean number of inflow transactions for the last three days.

float
required
Defaults to 0

The mean number of inflow transactions for the last week.

float
required
Defaults to 0

The mean number of inflow transactions for the last month.

float
required
Defaults to 0

The mean number of inflow transactions for the last three months.

float
required
Defaults to 0

The mean number of inflow transactions for the last six months.

float
required
Defaults to 0

The mean number of inflow transactions for the last twelve months.

float | null
required

The total sum of all inflow transactions for the last three days.

float | null
required

The total sum of all inflow transactions for the last week.

float | null
required

The total sum of all inflow transactions for the last month.

float | null
required

The total sum of all inflow transactions for the last three months.

float | null
required

The total sum of all inflow transactions for the last six months.

float | null
required

The total sum of all inflow transactions for the last twelve months.

float | null
required

The highest value inflow transaction in the last three days.

float | null
required

The highest value inflow transaction in the last week.

float | null
required

The highest value inflow transaction in the last month.

float | null
required

The highest value inflow transaction in the last three months.

float | null
required

The highest value inflow transaction in the last six months.

float | null
required

The highest value inflow transaction in the last twelve months.

float | null
required

The mean incoming value of all transactions in the last three days.

float | null
required

The mean incoming value of all transactions in the last week.

float | null
required

The mean incoming value of all transactions in the last month.

float | null
required

The mean incoming value of all transactions in the last three months.

float | null
required

The mean incoming value of all transactions in the last six months.

float | null
required

The mean incoming value of all transactions in the last twelve months.

int32
required
Defaults to 0

To total number of outflow transactions in the last three days.

int32
required
Defaults to 0

To total number of outflow transactions in the last week.

int32
required
Defaults to 0

To total number of outflow transactions in the last month.

int32
required
Defaults to 0

To total number of outflow transactions in the last three months.

int32
required
Defaults to 0

To total number of outflow transactions in the last six months.

int32
required
Defaults to 0

To total number of outflow transactions in the last twelve months.

int32
required
Defaults to 0

The maximum number of outflow transactions for the last three days.

int32
required
Defaults to 0

The maximum number of outflow transactions for the last week.

int32
required
Defaults to 0

The maximum number of outflow transactions for the last month.

int32
required
Defaults to 0

The maximum number of outflow transactions for the last three months.

int32
required
Defaults to 0

The maximum number of outflow transactions for the last six months.

int32
required
Defaults to 0

The maximum number of outflow transactions for the last twelve months.

float
required
Defaults to 0

The mean number of outflow transactions for the last three days.

float
required
Defaults to 0

The mean number of outflow transactions for the last week.

float
required
Defaults to 0

The mean number of outflow transactions for the last month.

float
required
Defaults to 0

The mean number of outflow transactions for the last three months.

float
required
Defaults to 0

The mean number of outflow transactions for the last six months.

float
required
Defaults to 0

The mean number of outflow transactions for the last twelve months.

float | null
required

The total sum of all outflow transactions for the last three days.

float | null
required

The total sum of all outflow transactions for the last week.

float | null
required

The total sum of all outflow transactions for the last month.

float | null
required

The total sum of all outflow transactions for the last three months.

float | null
required

The total sum of all outflow transactions for the last six months.

float | null
required

The total sum of all outflow transactions for the last twelve months.

float | null
required

The highest value outflow transaction in the last three days.

float | null
required

The highest value outflow transaction in the last week.

float | null
required

The highest value outflow transaction in the last month.

float | null
required

The highest value outflow transaction in the last three months.

float | null
required

The highest value outflow transaction in the last six months.

float | null
required

The highest value outflow transaction in the last twelve months.

float | null
required

The mean outgoing value of all transaction in the last three days.

float | null
required

The mean outgoing value of all transaction in the last week.

float | null
required

The mean outgoing value of all transaction in the last month.

float | null
required

The mean outgoing value of all transaction in the last three months.

float | null
required

The mean outgoing value of all transaction in the last six months.

float | null
required

The mean outgoing value of all transaction in the last twelve months.

int32
required
Defaults to 0

The number of days that no transactions occurred within the last three days.

int32
required
Defaults to 0

The number of days that no transactions occurred within the last week.

int32
required
Defaults to 0

The number of days that no transactions occurred within the last month.

int32
required
Defaults to 0

The number of days that no transactions occurred within the last three months.

int32
required
Defaults to 0

The number of days that no transactions occurred within the last six months.

int32
required
Defaults to 0

The number of days that no transactions occurred within the last twelve months.

int32
required
Defaults to 0

The number of days since the last transaction occurred.

int32
required
Defaults to 0

The number of days since the last inflow transaction occurred.

int32
required
Defaults to 0

The number of days since the last outflow transaction occurred.

int32
required
Defaults to 0

The number of days between when the risk insight request was made and the first transaction.

object | null
required

Aggregate metrics calculated based on the user's transactions from checking, savings, credit, and loan accounts. However, internal transfers (transfers between accounts belonging to the same link) are not used in the calculation.

ℹ️

Note

If there is not enough transactional data for a given period, we return null. For example, if the account has only been open for 15 days (or you have only provided data for just 15 days), we return values for _3d, _1w, and _1m, however for _3m we will return null as there is no data for months two and three.

float | null
required

The highest value of positive cash flow transactions in the last three days.

float | null
required

The highest value of positive cash flow transactions the last week.

float | null
required

The highest value of positive cash flow transactions the last month.

float | null
required

The highest value of positive cash flow transactions the last three months.

float | null
required

The highest value of positive cash flow transactions the last six months.

float | null
required

The highest value of positive cash flow transactions the last twelve months.

float | null
required

The highest value of negative cash flow transactions in the last three days.

float | null
required

The highest value of negative cash flow transactions in the last week.

float | null
required

The highest value of negative cash flow transactions in the last month.

float | null
required

The highest value of negative cash flow transactions in the last three months.

float | null
required

The highest value of negative cash flow transactions in the last six months.

float | null
required

The highest value of negative cash flow transactions in the last twelve months.

float | null
required

The mean value of the positive cash flow transactions in the last three days.

float | null
required

The mean value of the positive cash flow transactions in the last week.

float | null
required

The mean value of the positive cash flow transactions in the last month.

float | null
required

The mean value of the positive cash flow transactions in the last three months.

float | null
required

The mean value of the positive cash flow transactions in the last six months.

float | null
required

The mean value of the positive cash flow transactions in the last twelve months.

float | null
required

The mean value of the negative cash flow transactions in the last three days.

float | null
required

The mean value of the negative cash flow transactions in the last week.

float | null
required

The mean value of the negative cash flow transactions in the last month.

float | null
required

The mean value of the negative cash flow transactions in the last three months.

float | null
required

The mean value of the negative cash flow transactions in the last six months.

float | null
required

The mean value of the negative cash flow transactions in the last twelve months.

float | null
required

The sum total of all transactions leading to a positive cash flow in the last three days.

float | null
required

The sum total of all transactions leading to a positive cash flow in the last week.

float | null
required

The sum total of all transactions leading to a positive cash flow in the last month.

float | null
required

The sum total of all transactions leading to a positive cash flow in the last three months.

float | null
required

The sum total of all transactions leading to a positive cash flow in the last six months.

float | null
required

The sum total of all transactions leading to a positive cash flow in the last twelve months.

float | null
required

The positive cash flow trend based on the sum of all positive transactions in the last three days.

float | null
required

The positive cash flow trend based on the sum of all positive transactions in the last week.

float | null
required

The positive cash flow trend based on the sum of all positive transactions in the last month.

float | null
required

The positive cash flow trend based on the sum of all positive transactions in the last three months.

float | null
required

The positive cash flow trend based on the sum of all positive transactions in the last six months.

float | null
required

The positive cash flow trend based on the sum of all positive transactions in the last twelve months.

float | null
required

The sum total of all transactions leading to a negative cash flow in the last three days.

float | null
required

The sum total of all transactions leading to a negative cash flow in the last week.

float | null
required

The sum total of all transactions leading to a negative cash flow in the last month.

float | null
required

The sum total of all transactions leading to a negative cash flow in the last three months.

float | null
required

The sum total of all transactions leading to a negative cash flow in the last six months.

float | null
required

The sum total of all transactions leading to a negative cash flow in the last twelve months.

float | null
required

The negative cash flow trend based on the sum of all negative transactions in the last three days.

float | null
required

The negative cash flow trend based on the sum of all negative transactions in the last week.

float | null
required

The negative cash flow trend based on the sum of all negative transactions in the last month.

float | null
required

The negative cash flow trend based on the sum of all negative transactions in the last three months.

float | null
required

The negative cash flow trend based on the sum of all negative transactions in the last six months.

float | null
required

The negative cash flow trend based on the sum of all negative transactions in the last twelve months.

float | null
required

The ratio between sum_positive / sum_negative in the last three days.

ℹ️ If the ratio is greater than 1, it means that the user has more income than outgoing, indicating that they spend less than they earn.

Note: In the case that there have been no outgoing transactions, the value will be null.

float | null
required

The ratio between sum_positive / sum_negative in the last week.

ℹ️ If the ratio is greater than 1, it means that the user has more income than outgoing, indicating that they spend less than they earn.

Note: In the case that there have been no outgoing transactions, the value will be null.

float | null
required

The ratio between sum_positive / sum_negative in the last month.

ℹ️ If the ratio is greater than 1, it means that the user has more income than outgoing, indicating that they spend less than they earn.

Note: In the case that there have been no outgoing transactions, the value will be null.

float | null
required

The ratio between sum_positive / sum_negative in the last three months.

ℹ️ If the ratio is greater than 1, it means that the user has more income than outgoing, indicating that they spend less than they earn.

Note: In the case that there have been no outgoing transactions, the value will be null.

float | null
required

The ratio between sum_positive / sum_negative in the last six months.

ℹ️ If the ratio is greater than 1, it means that the user has more income than outgoing, indicating that they spend less than they earn.

Note: In the case that there have been no outgoing transactions, the value will be null.

float | null
required

The ratio between sum_positive / sum_negative in the last twelve months.

ℹ️ If the ratio is greater than 1, it means that the user has more income than outgoing, indicating that they spend less than they earn.

Note: In the case that there have been no outgoing transactions, the value will be null.

float | null
required

The net cash flow in the last three days.

float | null
required

The net cash flow in the last week.

float | null
required

The net cash flow in the last month.

float | null
required

The net cash flow in the last three months.

float | null
required

The net cash flow in the last six months.

float | null
required

The net cash flow in the last twelve months.

float | null
required

The net cash flow trend in the last three days months.

float | null
required

The net cash flow trend in the last week.

float | null
required

The net cash flow trend in the last month.

float | null
required

The net cash flow trend in the last three months.

float | null
required

The net cash flow trend in the last six months.

float | null
required

The net cash flow trend in the last twelve months.

category_metrics
array of objects
required

An array of aggregate metrics regarding the transaction categories and subcategories that Belvo has identified within the user's transaction history.

In the array, Belvo only returns categories that have been identified.

category_metrics*
object
string | null

The name of the transaction category.

Get transaction categorization
With Transaction categorization, we clean and categorize transactions for you, turning raw data into actionable insights. To enable this feature, just reach out to us, and we'll get right to it.

We return one of the following enum values:

  • Bills & Utilities
  • Credits & Loans
  • Deposits
  • Fees & Charges
  • Food & Groceries
  • Home & Life
  • Income & Payments
  • Insurance
  • Investments & Savings
  • Online Platforms & Leisure
  • Personal Shopping
  • Taxes
  • Transfers
  • Transport & Travel
  • Unknown*
  • Withdrawal & ATM
  • null

* For clients not using our Transaction Categorization product, we return null instead.

Bills & Utilities Credits & Loans Deposits Fees & Charges Food & Groceries Home & Life Income & Payments Insurance Investments & Savings Online Platforms & Leisure Personal Shopping Taxes Transfers Transport & Travel Unknown Withdrawal & ATM

string | null

The transaction subcategory.

Get transaction categorization
For clients not using our Transaction categorization, we return null instead. To enable this feature, just reach out to us, and we'll get right to it.

We return one of the following enum values:

  • Electricity & Energy
  • Rent
  • Telecommunications
  • Water
  • Auto
  • Credit Card
  • Instalment
  • Interest & Charges
  • Mortgage
  • Pay Advance
  • Personal
  • Adjustments
  • Bank Fees
  • Chargeback
  • Refund
  • Blocked Balances
  • Alimony
  • Alcohol & Tobacco
  • Bakery & Coffee
  • Bars & Nightclubs
  • Convenience Store
  • Delivery
  • Groceries
  • Restaurants
  • Education
  • Gyms & Fitness
  • Hair & Beauty
  • Health
  • Home Decor & Appliances
  • Laundry & Dry Cleaning
  • Pharmacies
  • Professional Services
  • Veterinary Services
  • Freelance
  • Interest
  • Retirement
  • Salary
  • Government
  • Home Insurance
  • Auto Insurance
  • Health & Life Insurance
  • Savings
  • Fixed income
  • Equity
  • Investment Funds
  • Derivatives
  • Cryptocurrencies
  • Apps, Software and Cloud Services
  • Events, Parks and Museums
  • Gambling
  • Gaming
  • Lottery
  • Movie & Audio
  • Books & News
  • Clothing & Accessories
  • Department Store
  • Electronics
  • E-commerce
  • Gifts
  • Office Supplies
  • Pet Supplies
  • Auto Tax & Fees
  • Donation
  • Government Fees
  • Income Tax
  • Real Estate Tax & Fees
  • Tax Return
  • Accommodation
  • Auto Expenses
  • Auto Rental
  • Flights
  • Gas
  • Mileage Programs
  • Parking & Tolls
  • Public Transit
  • Taxis & Rideshares
  • Other
  • null

Electricity & Energy Rent Telecommunications Water Auto Credit Card Instalment Interest & Charges Mortgage Pay Advance Personal Adjustments Bank Fees Chargeback Refund Blocked Balances Alimony Alcohol & Tobacco Bakery & Coffee Bars & Nightclubs Convenience Store Delivery Groceries Restaurants Education Gyms & Fitness Hair & Beauty Health Home Decor & Appliances Laundry & Dry Cleaning Pharmacies Professional Services Veterinary Services Freelance Interest Retirement Salary Government Home Insurance Auto Insurance Health & Life Insurance Savings Fixed income Equity Investment Funds Derivatives Cryptocurrencies Apps, Software and Cloud Services Events, Parks and Museums Gambling Gaming Lottery Movie & Audio Books & News Clothing & Accessories Department Store Electronics E-commerce Gifts Office Supplies Pet Supplies Auto Tax & Fees Donation Government Fees Income Tax Real Estate Tax & Fees Tax Return Accommodation Auto Expenses Auto Rental Flights Gas Mileage Programs Parking & Tolls Public Transit Taxis & Rideshares Other

float | null

The net amount of the transactions for this category in the last three months (calculated as the total incoming - total outgoing transactions for this category).

float | null

The ratio of net_amount_3m divided by the sum of all incoming categorized transactions (including the current category) for the same period.

Note: If there are no inflow transactions for the period, this value will return null.

float | null

The net category transaction trend (incoming - outgoing transactions for the category) for the period.

Language
Credentials
: