# Introduction To improve performance and provide a smoother process, our API supports asynchronous workflows and requests. Our asynchronous functionality can be divided into: - **Asynchronous historical data workflow (for single links)** Removes the need for POST calls after link creation to retrieve core information about the link. - **Asynchronous historical data workflow (for recurrent links)** Removes the need for POST calls after link creation to retrieve core information about the link and enables you to receive updates for any changes in the information. - **Asynchronous real-time POST calls (both single and recurrent links)** Eliminate the risk of timeouts and improve your data flow. ## Asynchronous historical data workflow (single links) Whether you create a single link via our API or use the widget to create your links, you can choose to asynchronously receive the historical information for your user by adding the `fetch_resources` parameter to your request: Widget ```shell Generate Widget Token URL curl --request POST \ --url https://sandbox.belvo.com/api/token/ \ --header 'accept: application/json' \ --header 'content-type: application/json' \ --data '{see request body below}' ``` ```json Widget Token Request Body { "id": "YOUR_SECRET_ID", "password": "YOUR_SECRET_PASSWORD", "external_id": "asynchronous-historical-request", "scopes": "read_institutions,write_links", "fetch_historical": true, "fetch_resources": [ "FINANCIAL_STATEMENTS", "INVOICES", "TAX_RETURNS", "TAX_STATUS", "TAX_COMPLIANCE_STATUS", "TAX_RETENTIONS" ] } ``` API ```shell Create Link URL curl --request POST \ --url https://sandbox.belvo.com/api/links/ \ --header 'accept: application/json' \ --header 'content-type: application/json' \ --data '{see request body below}' ``` ```json Link Request Body { "institution": "erebor_mx_retail", "username": "bnk100", "password": "full", "external_id": "asynchronous-historical-request", "access_mode": "single", "fetch_resources": [ "ACCOUNTS", "TRANSACTIONS", "OWNERS", "BILLS", "INVESTMENTS", "INVESTMENT_TRANSACTIONS" ] } ``` Once the link is created, Belvo will retrieve all the data available for the resources you’ve specified and notify you via webhook once the information is ready for you to retrieve: For more details regarding which resources you can send through, see our Register a new link request API reference. ```mermaid sequenceDiagram autonumber participant App as Application participant Belvo as Belvo participant Inst as Institution App->>Belvo: Create a single Link using the widget Note over App,Belvo: fetch_resources = [OWNERS, ACCOUNTS, TRANSACTIONS] Belvo->>Inst: Connect and confirm link creation Belvo-->>App: 201 - Created Note over App,Inst: Belvo retrieves historical OWNER, ACCOUNTS, and TRANSACTION information for the Link ID Belvo-->>App: WEBHOOK historical_update (OWNERS) App->>Belvo: GET /owners/?link={link.id} Belvo-->>App: 200 + Owner Details Belvo-->>App: WEBHOOK historical_update (ACCOUNTS) App->>Belvo: GET /accounts/?link={link.id} Belvo-->>App: 200 + Account Details Belvo-->>App: WEBHOOK historical_update (TRANSACTIONS) App->>Belvo: GET /transactions/?link={link.id} Belvo-->>App: 200 + Transaction Details ``` 1. **Register a link using the Connect Widget** When you generate your access_token, make sure to pass the `fetch_resources` parameter. Once your user connects to their account using our Connect Widget, Belvo will respond with the link `id` and start to asynchronously load the resources you listed in `fetch_resources` . 2. **Wait for webhooks** As soon as we retrieve data for each resource you listed, you'll receive a `historical_update` webhook for that resource. For each webhook you receive, you need to make a GET List request to Belvo to get the data. In the code block below, you can see an example of the webhook you will receive and the request you need to send to retrieve the data. ```json { "webhook_id": "aadf41a1fc8e4f79a49f7f04027ac999", "webhook_type": "TRANSACTIONS", "webhook_code": "historical_update", "link_id": "16f68516-bcbc-4cf7-b815-c500d4204e28", // The link that the data belongs to "request_id": "4363b08b-51eb-4350-9c74-5df5ac92a7f6", "external_id": "optional_parameter_you_can_provide", "data": { "total_transactions": 19, // Total number of transactions found "total_inflow_transactions": 10, // Total number of inflow transactions "total_outflow_transactions": 9, // Total number of outflow transactions "first_transaction_date": "2017-01-03", // First transaction date "last_transaction_date": "2020-03-25" // Last transaction date } } ``` ```curl curl --request GET \ --url 'https://sandbox.belvo.com/api/transactions/?link=16f68516-bcbc-4cf7-b815-c500d4204e28' \ --header 'accept: application/json' ``` br ## Asynchronous historical data workflow (recurrent links) Whether you create a recurrent link via our API or use the widget to create your links, you will asynchronously receive the historical information for your user, along with regular updates to any changes to the user's information. Once the link is created, Belvo will retrieve all the data available for the resources you’ve specified and notify you via webhook once the information is ready for you to retrieve: ```mermaid sequenceDiagram autonumber participant App as Application participant Belvo as Belvo participant Inst as Institution App->>Belvo: Create a recurrent Link using the widget Belvo->>Inst: Connect and confirm link creation Belvo-->>App: 201 - Created Note over App,Inst: Belvo retrieves historical OWNER, ACCOUNTS, and TRANSACTION information for the Link ID Belvo-->>App: WEBHOOK historical_update (per resource) App->>Belvo: GET /{resource}/?link={link.id} Belvo-->>App: 200 + resource Details Note over App,Inst: At your scheduled Link update frequency, Belvo checks for new information for each link per resource Belvo-->>App: WEBHOOK new_{resource}_available App->>Belvo: GET /{resource}/?link={link.id} Belvo-->>App: 200 + resource Details ``` br 1. **Register a link using the Connect Widget** Once your user connects to their account using our Connect Widget, Belvo will respond with the link `id` and start to asynchronously load the core resources for the link type. 2. **Wait for webhooks (historical)** As soon as we retrieve data for each resource, you'll receive a `historical_update` webhook for that resource. For each webhook you receive, you need to make a GET List request to Belvo to get the data. In the code block below, you can see an example of the webhook you will receive and the request you need to send to retrieve the data. 3. **Wait for webhooks (new resource available)** Depending on your update frequency, we'll send you a `new_{resource}_updated` webhook, indicating that we have retrieved new data for the link. ## Asynchronous real-time POST calls (both single and recurrent links) By making your individual POST calls asynchronous, you eliminate the risk of receiving timeout errors and can design your information aggregation in a more expected manner. > 📘 At the moment, our asynchronous real-time POST call applies to the following requests: - POST Retrieve Transactions - POST Retrieve Invoices - POST Retrieve Employments in Brazil - POST Retrieve Employment Records in Mexico - POST Retrieve Financial Statements in Mexico We are continuously rolling out this feature to our remaining POST methods. ```mermaid sequenceDiagram autonumber participant App as Application participant Belvo as Belvo participant Inst as Institution rect rgba(0, 100, 255, .05) Note over App,Inst: Link creation App->>Belvo: Create a Recurrent Link using the Widget Belvo->>Inst: Connect Belvo-->>App: 201 OK + Link ID end rect rgba(0, 200, 100, .05) Note over App,Inst: Async transactions request App->>Belvo: POST /transactions/{Link ID, date from, date to}/ Note over App,Belvo: X-Belvo-Request-Mode: async Belvo-->>App: 202 Accepted Note over App,Belvo: request_id Belvo->>Inst: Retrieve transaction information for the period indicated Belvo-->>App: new_transactions_available webhook App->>Belvo: GET /transactions/{link_id}/ end ``` 1. **Register a link using the Connect Widget** Your user connects to their account using our Connect Widget. After they've successfully connected, you'll receive a Link ID that you'll need to use in order to make further requests about the user. 2. **Send a POST request with new `async` header** Make a POST call using `X-Belvo-Request-Mode` set to `async`. You'll receive a `202 - Accepted` response with a `request_id` in the body. We recommend you store this `request_id` so later when you receive a webhook you'll know to which request the webhook is in response to. 3. **Wait for webhook** As soon as you make your POST request, Belvo will begin retrieving data about the user. We send a webhook once all the requested information has been retrieved. When you receive the webhook, you can make a GET request to the appropriate endpoint to retrieve the information. ```curl curl --location --request POST 'https://sandbox.belvo.com/api/transactions/' \ --header 'X-Belvo-Request-Mode: async' \ --header 'Authorization: Basic ' \ --header 'Content-Type: application/json' \ --data-raw '{ "link": "bcca0da9-a4c6-4830-9676-1d54682851d9", "date_from": "2022-12-17", "date_to": "2023-01-16" } ``` ```curl curl --location --request POST 'https://sandbox.belvo.com/api/invoices/' \ --header 'X-Belvo-Request-Mode: async' \ --header 'Authorization: Basic ' \ --header 'Content-Type: application/json' \ --data-raw '{ "link": "bcca0da9-a4c6-4830-9676-1d54682851d9", "date_from": "2022-12-17", "date_to": "2023-01-16", "type": "OUTFLOW" } ``` ```json { "request_id": "3f58b8a6f025402f8de4a4cc55d38705" } ``` ## Manually triggering a historical **update** In Beta The **Trigger a historical update for a link** method is currently in Open Beta for all clients to use. We encourage you to try it out and provide feedback. You can also manually trigger an asynchronous historical update for a link's data by using our Trigger a historical update for a link method. The flow is very similar to when you first create a link: 1. You make a `POST` request to the endpoint. 2. Belvo returns a `202 Accepted` response with a `request_id`. 3. When the data is ready, Belvo sends a `historical_update` webhook. 4. You can then make a `GET` request to retrieve the updated data. Cooldown Period To prevent duplicate requests, the **Refresh historical data for a link** endpoint has a 10-minute cooldown period for each link. If you make a request for the same link within this period, you will receive a synchronous `409 Conflict` error. ## Best Practices #### Do I need to send up a webhook URL even for single links?** Yes, you will need to have webhooks set up to make use of our asynchronous functionality. #### Do I need to response to the webhook when I receive it? Yes, once you receive a webhook send a `202 - Accepted webhook ` to Belvo within five seconds to confirm that you have received the webhook. Otherwise, our API will retry the request. If you see any issues with the JSON, please respond to Belvo with a `400 Bad Request`, including the request ID. #### Can I use Asynchronous POST requests for any type of link? Yes! Whether the link is single or recurrent, whenever you make a POST call you can use the `async` header.