Sign in

v1

latestOpenAPI 3.0.22026-08-061464031.4 MB
Recurring Expenses

Retrieve recurring expenses for a link

Retrieve recurring expense 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/recurring-expenses/

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.

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.

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

Example request

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

Response

Ok (when save_data=false)

idstring uuid

Belvo's unique identifier for the current item.

namestring nullable required

The name for the recurring expense.

ℹ️ Note: This information is taken from the description section of a transaction and then normalized to provide you with an easy-to-read name. As such, sometimes the name will reflect the merchant the payment is made to (for example, Netflix.com), while for other recurring expenses, this could be something like "Monthly payment to John".

frequency'MONTHLY' required

The frequency at which this recurring expense occurs.

ℹ️ Note: Belvo only identifies MONTHLY frequencies.

average_transaction_amountnumber float required

The average transaction amount of the recurring expense.

median_transaction_amountnumber float required

The median transaction amount of the recurring expense.

days_since_last_transactioninteger required

Number of days since the last recurring expense occurred.

Based on the frequency, you can infer how many days until the next charge will occur.

category'Bills & Utilities' | 'Credits & Loans' | 'Insurance' | 'Online Platforms & Leisure' | 'Transport & Travel' | 'Taxes' required

The transaction category for the recurring expense. For more information on the available categories, please see our <a href="https://developers.belvo.com/docs/banking#categorizing-transactions" target="_blank">Transaction categorization documentation</a>.

  • Online Platforms & Leisure (Netflix, Spotify, Gym Memberships)
  • Bills & Utilities (electricity, telephone, internet)
  • Credits & Loans (credit card cash advances, student loan, watercraft lease)
  • Insurance (home, car, and health & life insurance)
  • Transport & Travel (Uber trip, airbnb, parking)
  • Taxes (service fee, donation, court taxes)
payment_type'SUBSCRIPTION' | 'REGULAR' nullable required

The type of recurring expense. We return one of the following values:

  • SUBSCRIPTION
  • REGULAR

Example response

[
  {
    "id": "0d3ffb69-f83b-456e-ad8e-208d0998d71d",
    "account": {
      "id": "0d3ffb69-f83b-456e-ad8e-208d0998d71d",
      "link": "30cb4806-6e00-48a4-91c9-ca55968576c8",
      "institution": {
        "name": "erebor_mx_retail"
      },
      "collected_at": "2022-02-09T08:45:50.406032Z",
      "created_at": "2022-02-09T08:45:50.406032Z",
      "last_accessed_at": "2021-03-09T10:28:40.000Z",
      "category": "CHECKING_ACCOUNT",
      "balance_type": "ASSET",
      "overdraft": {
        "arranged": 5000.5,
        "used": 1000.5,
        "unarranged": 300.1
      },
      "type": "STANDARD_NACIONAL",
      "subtype": "FINANCIAMENTO_HABITACIONAL_SFH",
      "name": "Cuenta Perfiles- M.N. - MXN-666",
      "number": "4057068115181",
      "agency": "6272",
      "check_digit": "7",
      "balance": {
        "current": 5874.13,
        "available": 5621.12,
        "blocked": 60.32,
        "automatically_invested": 131.5
      },
      "currency": "BRL",
      "public_identification_name": "AGENCY/ACCOUNT",
      "public_identification_value": "0444/45722-0",
      "internal_identification": "92792126019929279212650822221989319252576",
      "credit_data": {
        "collected_at": "2022-02-09T08:45:50.406032Z",
        "credit_limit": 192000.9,
        "limits": [
          {
            "identification_number": "4453",
            "credit_limit": 1000.04,
            "used_amount": 400.04,
            "available_amount": 600,
            "type": "TOTAL_LIMIT",
            "consolidation_type": "INDIVIDUAL",
            "line_name": "CREDITO_A_VISTA",
            "line_name_additional_info": "Informações adicionais e complementares"
          }
        ],
        "cutting_date": "2019-12-11",
        "minimum_payment": 2400.3,
        "network": "MASTERCARD",
        "network_additional_info": "It's an orange card.",
        "cards": [
          {
            "identification_number": "4453"
          }
        ]
      },
      "loan_data": {
        "collected_at": "2022-02-09T08:45:50.406032Z",
        "loan_code": "92792126019929279212650822221989319252576",
        "contract_amount": 202000,
        "total_effective_cost": 209000,
        "loan_type": "HOME_EQUITY",
        "outstanding_balance": 182000,
        "interest_rates": [
          {
            "name": "NOMINAL",
            "type": "MONTHLY",
            "value": 7.85,
            "interest_rate_data": {
              "tax_type": "NOMINAL",
              "rate_type": "SIMPLE",
              "type": "MONTHLY",
              "calculation_base": "30/360",
              "reference_index_type": "FLOATING",
              "reference_index_subtype": "TR_TBF",
              "reference_index_info": "Additional information",
              "pre_fixed_rate": 0.062,
              "post_fixed_rate": 0.062,
              "additional_info": "Additional information"
            }
          }
        ],
        "fees": [
          {
            "value": 5.6,
            "name": "Renovação de cadastro",
            "code": "CADASTRO",
            "fee_charge_type": "SINGLE",
            "fee_charge": "FIXED",
            "rate": 0.062
          }
        ],
        "contracted_charges": [
          {
            "type": "LATE_PAYMENT_INTEREST_FEE",
            "info": "Late fee",
            "rate": 0.062
          }
        ],
        "collaterals": [
          {
            "type": "OPERACOES_GARANTIDAS_PELO_GOVERNO",
            "subtype": "CCR_CONVENIO_CREDITOS_RECIPROCOS",
            "currency": "BRL",
            "amount": 45391.89
          }
        ],
        "balloon_payments": [
          {
            "due_date": "2021-09-06",
            "currency": "BRL",
            "amount": 45391.89
          }
        ],
        "installments_contract_term_frequency": "MONTH",
        "installment_frequency": "MONTHLY",
        "installment_frequency_info": "Both the term and requency are the same.",
        "first_installment_due_date": "2020-03-01",
        "number_of_installments_total": 60,
        "number_of_installments_outstanding": 48,
        "number_of_installments_paid": 32,
        "number_of_installments_past_due": 2,
        "disbursement_dates": [
          "2021-09-23"
        ],
        "settlement_date": "2021-09-23",
        "contract_start_date": "2020-03-01",
        "contract_end_date": "2027-10-01",
        "contract_remaining_frequency": "MONTH",
        "contract_remaining_total": 20,
        "amortization_schedule": "SEM_SISTEMA_AMORTIZACAO",
        "amortization_schedule_info": "No need for a schedule.",
        "consignee_id": "60500998000135",
        "contract_number": "1324926521496"
      }
    },
    "name": "Netflix",
    "transactions": [
      {
        "amount": 2145.45,
        "description": "Netflix.com/march",
        "value_date": "2019-10-23"
      }
    ],
    "frequency": "MONTHLY",
    "average_transaction_amount": 32.9,
    "median_transaction_amount": 32.9,
    "days_since_last_transaction": 5,
    "category": "Online Platforms & Leisure",
    "payment_type": "SUBSCRIPTION"
  }
]