Incomes

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

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.

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

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

Belvo's Risk Insights resource exposes a set of features that can be used to improve your company's credit risk and opportunity decisions. This set of features can be used as building blocks to create or iterate on your own credit score using transactional banking data with the objective of improving the predictive power of your models. You can use these components as you require and according to what makes the most sense for your specific use case.

To calculate the risk insights, we take up to 90 days of transactional data from the user's checking, savings, loans, and credit card accounts. If no recurring insights can be identified, we return an empty array.

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.