To improve performance and provide a smoother workflow, our API supports asynchronous requests. By making your requests asynchronous, you eliminate the risk of receiving a timeout errors and can design your information aggregation in a more expected manner.

📘

At the moment, our asynchronous API only applies to our POST Retrieve Transactions method. However, we'll be rolling this out as the default to our remaining POST methods soon!

Flow

1. Register a link using the Connect Widget
   As usual, 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 one 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 --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"
}

{
  "request_id": ""
}

FAQ

Can I use Asynchronous 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.

Do I need to send up a webhook URL even for single links?

Yes, you will need to have webhooks set up in order to make use of our asynchronous functionality.

Implementation best practices

We highly recommend that once you receive the new_transactions_updated webhook that you automatically 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.