Tax returns (Webhooks)

Reference information for our Tax returns webhook events.

Historical update

As soon as your fiscal recurrent link is created, we asynchronously load the last five years of yearly tax returns as well as the 12 months of monthly tax returns. You will receive a historical_update notification for each type of tax return (yearly and monthly) whenever the tax return history is available for you to access.

{
  "webhook_id": "80fa38b7cad34950b210626abd86bfe9",
  "webhook_type": "TAX_RETURNS",
  "process_type": "historical_update",
  "webhook_code": "historical_update",
  "link_id": "2f5d361d-dad6-45d4-a0bf-26d479766067",
  "request_id": "4363b08b-51eb-4350-9c74-5df5ac92a7f6",
  "external_id": "your_external_id",
  "data": {
    "type": "yearly", // either yearly or monthly
    "total_tax_returns": 2, // Total number of tax returns found
    "first_tax_return_year": 2017, // First filed tax return
    "last_tax_return_year": 2018 // Last filed tax return
  }
}

{
  "webhook_id": "80fa38b7cad34950b210626abd866549",
  "webhook_type": "TAX_RETURNS",
  "process_type": "historical_update",
  "webhook_code": "historical_update",
  "link_id": "2f5d361d-dad6-45d4-a0bf-26d479766067",
  "data": {
    "type": "monthly", // either yearly or monthly
    "total_tax_returns": 7, // Total number of tax returns found
    "first_tax_return_year": 2017, // First filed tax return
    "last_tax_return_year": 2018 // Last filed tax return
  }
}

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

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

Where:

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

New tax returns available

You can receive a new_tax_returns_available notification whenever new tax returns are available for a fiscal recurrent link.

📘
We define new tax returns as all new tax returns found in the institution for this link. It could be the new tax returns from the last year or also tax returns added by the institution for previous years.

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

{
  "webhook_id": "351610c401e34e728900495fda5b970a",
  "webhook_type": "TAX_RETURNS",
  "process_type": "recurrent_update",
  "webhook_code": "new_tax_returns_available",
  "link_id": "331ba983-0cfa-4186-93fc-936f3946cca3",
  "request_id": "4363b08b-51eb-4350-9c74-5df5ac92a7f6",
  "external_id": "your_external_id",
  "data": {
    "type": "monthly", // can be either yearly or monthly
    "new_tax_returns": 1 // Total number of new tax returns found
  }
}

You can request more information about the tax returns with the following query to the Tax returns endpoint using the created_at filter:

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

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.

Updated 4 months ago