Historical update

As soon as your banking recurrent link is created, we asynchronously load the last 30 days of balances history. You will receive a historical_update notification whenever the last 30 days of balances are available for you to access.

{
  "webhook_id": "aadf41a1fc8e4f79a49f7f04027ac999",
  "webhook_type": "BALANCES",
  "webhook_code": "historical_update",
  "link_id": "16f68516-bcbc-4cf7-b815-c500d4204e28",
  "request_id": "4363b08b-51eb-4350-9c74-5df5ac92a7f6",
  "external_id": "your_external_id",
  "data": {
    "total_balances": 30, // Total number of balances found
    "first_balance_date": "2021-11-03", // First balance date
    "last_balance_date": "2021-12-03" // Last balance date
  }
}

Once you receive the notification, you can get further details by making the following request:

curl --request GET 'https://api.belvo.com/api/balances/?link={id}' \
-u [Secret Key ID]:[Secret Key PASSWORD]

client.balances.list({
  filters: {
    link: "{id}"
  }
})

client.Balances.list(link="{id}")

client.balances.list(params: {
  link: "{id}"
})

Where:

{id} is the link_id you receive in your historical_update notification.

New balances available

You can receive a new_balances_available notification whenever new balances are available for a banking recurrent link.

📘
We define new balances as balances found for a given link since the last update. For example, these could be new balances from the last 24 hours or new balances from a few days ago that were just computed from the new transactions added by the institution.

Once you receive the notification, you can query the Balances endpoint to pull the details of these new balances. For example, if you receive the following webhook:

{
  "webhook_id": "aadf41a1fc8e4f79a49f7f04027ac999",
  "webhook_type": "BALANCES",
  "webhook_code": "new_balances_available",
  "link_id": "16f68516-bcbc-4cf7-b815-c500d4204e28",
  "request_id": "4363b08b-51eb-4350-9c74-5df5ac92a7f6",
  "external_id": "your_external_id",
  "data": {
    "new_balances": 14 // Number of new balances found since last webhook event.
  }
}

You can request more information about the balances with the following query to the Balances endpoint using the value_date filter:

curl --request GET 'https://api.belvo.com/api/balances/?link={id}&value_date__range={date1},{date2}' \
-u [Secret Key ID]:[Secret Key PASSWORD]

client.balances.list({
  filters: {
    link: "{id}",
    value_date__range: "{date1},{date2}"
  }
})client.Balances.list(link="{id}",value_date__range="{date1},{date2}")

client.Balances.list(link="{id}",value_date__range="{date1},{date2}")

client.balances.list(params: {
  link: "{id}",
  value_date__range: "{date1},{date2}"
})

Where:

{id} is the link_id you received in the notification
{date1} is the date when you previously received a notification, in YYYY-MM-DD format.
{date2} is the date you received the latest notification, in YYYY-MM-DD format.