Incomes

🚧
Request transactions first
Before requesting incomes, you must first make a POST Retrieve Transactions request.
If you do not request the transactions, the analyses won't be able to be conducted.

Our Incomes resource provides you with information regarding the income sources of a banking link.

Use the Incomes resource to gather insights on an account's income sources for the past 365 days. The endpoint is particularly useful when you want to verify a person's income.

📘
The Incomes resource is only available for Checking and Savings accounts associated with banking links.

Use this resource to get information about a banking link's:

income source and confidence
stability and regularity scores
list of transactions used to determine the income source

We offer the following methods when it comes to interacting with Incomes:

Endpoints	Method	Description
Retrieve	`POST`	Retrieve income insights from a specific link. The period is up to 365 days and depends on the transaction history available for each bank.
List	`GET`	List the incomes associated with your Belvo account.
Resume	`PATCH`	Resume an Incomes retrieve session that was paused because an MFA token was required by the institution.
Detail	`GET`	Get the details of a specific income.
Destroy	`DELETE`	Delete a specific income from your Belvo account.

Getting better income data

For income verification to return accurate data, you user needs to connect the account that they receive their salary in. If they link an account that does not include their salary transactions, our API will return an empty array.

💡 To avoid receiving an empty array, make sure to indicate to your user that they should connect the account that receives their salary.

Additionally, we recommend implementing a mechanism where, if your user connects an account that does not contain salary transactions, you notify them that the account they connected contained no salary information and ask them to connect another account.

Recurring expenses

🚧
Request accounts and transactions first
Before requesting recurring expenses, 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.

Belvo's Recurring Expenses resource allows you to identify a user's regular payments for subscription services, such as Netflix or gym memberships, as well as utility payments, such as electricity or phone bills. This information is extremely useful when you want to help users manage their future obligations.

📘
The recurring expenses resource is only available for Checking and Savings accounts associated with banking links. We return information for up to 365 days.
If no recurring expenses can be identified, we return an empty array.

For each recurring transaction, we return the enriched data (type of transaction, category, average amounts) as well as supporting account and transaction information. Check our Recurring expenses API reference for detailed information on each data point we return.

[
  {
    "id": "076c66e5-90f5-4e01-99c7-50e32f65ae42",
    "account": {}, // Information about the account we found the recurring transaction in
    "name": "Netflix",
    "transactions": [ // Array of transactions we identified as being cyclical
      {
        "amount": 32.9,
        "description": "Netflix.com/march",
        "value_date": "2019-10-23"
      },
      {
        "amount": 32.9,
        "description": "Netflix.com/april",
        "value_date": "2019-10-23"
      },
      {
        "amount": 32.9,
        "description": "Netflix.com/may",
        "value_date": "2019-10-23"
      }
    ],
    "frequency": "MONTHLY", // How often the transaction occurs
    "average_transaction_amount": 32.9, // Average amount of the transaction
    "median_transaction_amount": 32.9,
    "days_since_last_transaction": 5, // Helps you identify how long until the next transaction
    "category": "Online Platforms & Leisure", // Category of the transaction
    "payment_type": "SUBSCRIPTION" // Category of payment method
  }
]

Endpoints	Method	Description
Retrieve	`POST`	Retrieve recurring expense insights from a specific link. The period is up to 365 days and depends on the transaction history available for each bank.
List	`GET`	List the recurring expense associated with your Belvo account.
Resume	`PATCH`	Resume a recurring expense retrieve session that was paused because an MFA token was required by the institution.
Detail	`GET`	Get the details of a recurring expense.
Destroy	`DELETE`	Delete a specific recurring expense from your Belvo account.

Risk insights

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

Building a credit model demands a meticulous analysis of data, variable calculation, and data cleansing. Belvo's Risk Insights resource offers a comprehensive list of pre-calculated features, providing data science teams building blocks to quickly create, iterate, and validate their models.

📘
To calculate the risk insights, we take up to 365 days of transactional data from the user's checking, savings, investment, loan, and credit card accounts.

Endpoints	Method	Description
Retrieve	`POST`	Retrieve risk insights for a specific link. The period is up to 90 days and depends on the transaction history available for each bank.
List	`GET`	List all the risk insight analyses associated with your Belvo account.
Resume	`PATCH`	Resume a risk insights retrieve session that was paused because an MFA token was required by the institution.
Detail	`GET`	Get the details of a risk insight analysis.
Destroy	`DELETE`	Delete a specific risk insight analysis from your Belvo account.