Historical update

As soon as your fiscal link is created, we asynchronously load the last three years of financial statements and will send you the following webhook:

In the webhook payload we include the number of financial statements received.

{
  "webhook_id": "aadf41a1fc8e4f79a49f7f04027ac999",
  "webhook_type": "FINANCIAL_STATEMENTS",
  "webhook_code": "historical_update",
  "process_type": "historical_update",
  "link_id": "2f8ca7a1-c28f-46f2-bb41-21633099a280",
  "request_id": "4363b08b-51eb-4350-9c74-5df5ac92a7f6",
  "external_id": "COHORT_32_User_6790023X5",
  "data": {
    "new_financial_statements": 3
  }
}

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

curl --request GET \
-u [Secret Key ID]:[Secret Key PASSWORD] \
'https://api.belvo.com/api/financial-statements/?link=link_id'

👍

For details about the response body, make sure to check out our List Financial Statements API reference documentation or Financial Statements Data Dictionary.

New financial statements available

🚧

Only applicable for asynchronous POST calls.

When you make an "ad hoc" request for financial statements (with the X-Belvo-Request-Mode: async header), Belvo will asynchronously retrieve the financial statement information and send you the following webhook:

In the webhook payload we include the number of new financial statements found for the link.

{
  "webhook_id": "aadf41a1fc8e4f79a49f7f04027ac999",
  "webhook_type": "FINANCIAL_STATEMENTS",
  "webhook_code": "new_financial_statements_available",
  "process_type": "async_post",
  "link_id": "16f68516-bcbc-4cf7-b815-c500d4204e28",
  "request_id": "4363b08b-51eb-4350-9c74-5df5ac92a7f6",
  "external_id": "COHORT_32_User_6790023X5",
  "data": {
    "new_financial_statements": 1
  }
}

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

curl --request GET \
-u [Secret Key ID]:[Secret Key PASSWORD] \
'https://api.belvo.com/api/financial-statements/?link=link_id'

Errors while extracting Financial Statements

In order to provide you greater visibility regarding the extraction of Financial Statement data, we have included a new error field in the response payload for each financial statement you will still receive.

If, for a given year where a financial statement is available, we are not able to retrieve data due to the institution not providing the information in the correct format, the error field will indicate the reason behind the unsuccessful extraction:

[
  {
    "id": "0d3ffb69-f83b-456e-ad8e-208d0998d71d",
    "link": "30cb4806-6e00-48a4-91c9-ca55968576c8",
    "collected_at": "2022-02-09T08:45:50.406032Z",
    "created_at": "2022-02-09T08:45:50.406032Z",
    "error": "Unable to validate if the user has an available financial statement for the specified year.",
    "year": 2020,
    "currency": "MXN",
    "balance_sheet": null,
    "income_statement": null
  }
]

The possible error messages are:

• Unable to validate if the user has an available financial statement for the specified year.
• No available financial statement found for the user for the specified year, preventing data extraction.
• Unable to verify if the user has _conceptos vigentes_ for the specified year.
• The fiscal institution provided the financial statement in an unrecognized format.

If you receive financial statement payloads with these errors, please contact our support team.