v1

latestOpenAPI 3.0.22026-08-061464031.4 MB

Incomes

Retrieve incomes for a link

Retrieve income insights for <b>checking and savings accounts</b> from a specific link. You can receive insights for a period of up to 365 days, depending on the transaction history available for each institution.

post/api/incomes/

Query parameters

omitstring

Omit certain fields from being returned in the response. For more information, see our <a href="https://developers.belvo.com/docs/searching-and-filtering" target="_blank">Filtering responses</a> DevPortal article.

fieldsstring

Return only the specified fields in the response. For more information, see our <a href="https://developers.belvo.com/docs/searching-and-filtering" target="_blank">Filtering responses</a> DevPortal article.

Request body

linkstring uuid required

The link.id you want to retrieve information for.

allowed_income_typesEnumInvoiceAllowedIncomeTypesRequest[]

The categories of the incomes you want to get information for.

minimum_confidence_level'HIGH' | 'MEDIUM' | 'LOW'

The minimum confidence level of the incomes you want to get information for.

You can send through one of the following values:

HIGH
MEDIUM
LOW

date_fromstring date

The date from which you want to start getting data for, in YYYY-MM-DD format.

⚠️ The value of date_from cannot be greater than date_to.

date_tostring date

The date you want to stop getting data for, in YYYY-MM-DD format.

⚠️ The value of date_to cannot be greater than today's date (in other words, no future dates).

tokenstring

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

save_databoolean

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.

Example request

{
  "link": "c81a1dea-6dd6-4999-8b9f-541ee8197058",
  "allowed_income_types": [
    "SALARY"
  ],
  "minimum_confidence_level": "HIGH",
  "date_from": "2020-08-05",
  "date_to": "2020-10-05",
  "token": "1234ab",
  "save_data": true
}

Response

Ok (when save_data=false)

idstring uuid required

Belvo's unique identifier for the current item.

linkstring uuid nullable required

The link.id the data belongs to.

created_atstring date-time required

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

income_source_type'BANK' required

The type of source we generate income insights from. We return one of the following enum values:

BANK

first_transaction_datestring date nullable required

The date when the first transaction occurred, in YYYY-MM-DD format.

last_transaction_datestring date required

The date when when the last transaction occurred, in YYYY-MM-DD format.

best_working_day_to_chargeinteger required

The best working day of the month to charge the user.

good_working_days_to_chargeinteger[] required

Additional working days that have been identified as good days to charge the user.

number_of_income_streamsinteger required

Number of total income streams analized.

monthly_averagenumber float required

Average amount of income received per month across all the accounts for the specific user.

monthly_average_regularnumber float required

Average amount of regular income (with a frequency of MONTHLY, FORTNIGHTLY, or WEEKLY) received per month for the specific user.

monthly_average_irregularnumber float required

Average amount of irregular income (with a frequency of SINGLE or IRREGULAR) received per month for the specific user.

monthly_average_low_confidencenumber float required

Average amount of income received per month for the specific user with LOW confidence.

monthly_average_medium_confidencenumber float required

Average amount of income received per month for the specific user with MEDIUM confidence.

monthly_average_high_confidencenumber float required

Average amount of income received per month for the specific user with HIGH confidence.

total_income_amountnumber float required

Total amount of all income received for the specific user.

total_regular_income_amountnumber float required

Total amount of regular income (with a frequency of MONTHLY, FORTNIGHTLY, WEEKLY) for the specific user.

total_irregular_income_amountnumber float

Total amount of irregular income (with a frequency of SINGLE or IRREGULAR) for the specific user.

total_low_confidencenumber float required

Total amount of income for the specific user with LOW confidence.

total_medium_confidencenumber float required

Total amount of income for the specific user with MEDIUM confidence.

total_high_confidencenumber float required

Total amount of income for the specific user with HIGH confidence.

Example response

{
  "id": "0d3ffb69-f83b-456e-ad8e-208d0998d71d",
  "link": "30cb4806-6e00-48a4-91c9-ca55968576c8",
  "created_at": "2022-02-09T08:45:50.406032Z",
  "income_streams": [
    {
      "account_id": "EBACA-89077589",
      "income_type": "SALARY",
      "frequency": "MONTHLY",
      "monthly_average": 2500,
      "monthly_median": 2200,
      "average_income_amount": 2500,
      "last_income_amount": 2500,
      "currency": "BRL",
      "last_income_description": "Salário",
      "last_income_date": "2023-02-09",
      "stability": 1,
      "regularity": 1,
      "lookback_periods": 9,
      "full_periods": 9,
      "periods_with_income": 9,
      "number_of_incomes": 9,
      "confidence": "HIGH"
    }
  ],
  "income_source_type": "BANK",
  "first_transaction_date": "2022-06-09",
  "last_transaction_date": "2023-02-09",
  "best_working_day_to_charge": 22,
  "good_working_days_to_charge": [
    17,
    7,
    2
  ],
  "number_of_income_streams": 1,
  "monthly_average": 2500,
  "monthly_average_regular": 2500,
  "monthly_average_high_confidence": 2500,
  "total_income_amount": 22500,
  "total_regular_income_amount": 22500,
  "total_high_confidence": 22500
}