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 thelink_id
you receive in yourhistorical_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 thelink_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