Links and Institutions
At Belvo, we use two core concepts (and endpoints) that you need to be aware of while integrating and using the Belvo API: ๐ฆ Institutions and ๐ Links.
Institutions
An institution is an entity that Belvo can access information from. It can be a:
- bank institution, such as Banamex retail banking or HSBC business banking.
- fiscal institution, such as the Servicio de Administraciรณn Tributaria (SAT) in Mexico.
- employment institution, such as Instituto Mexicano del Seguro Social (IMSS) in Mexico.
Belvo resources and institutions
Not all institutions support the same Belvo resources. For example, the Accounts resource (used with banking institutions) won't be supported in fiscal institutions. To know which resources you can use for each institution, look at the
resources
array when you use one of the methods in the table below.
You can see a complete list of banking institutions by either consulting our Institutions page, or querying the following resources:
Links
Whenever a user connects to their institution using the Belvo API, we create a Link. A Link is a set of encrypted credentials, for example the username and password, that is associated with the user. You will always need to first register a Link before being able to access information specific to that end user.
You can perform the following operations with our Links resource:
Endpoint | Method | Description |
---|---|---|
Register | POST | Register a new link from a financial institution to your Belvo account. |
List | GET | List all links currently associated with your Belvo account. |
Resume | PATCH | Resume a link registering session that was paused because an MFA token was required by the institution. |
Detail | GET | Get the details of a specific link. |
Update | PUT | Update the password of a specific link. |
Destroy | DELETE | Delete permanently a link and all associated accounts, transactions, and owners information from your Belvo account. |
Use your own identifier ๐คฉ
We really recommend you make use of the
external_id
parameter when creating links as this will allow you to have your own unique identifier for a link in your own database. Check out our Link creation best practices article for more information.
Recurrent links
With recurrent links, Belvo automatically refreshes information weekly and notifies you via webhook so you always have up-to-date data. Then, when you receive the webhook, you can use GET requests to the List or Detail endpoints to instantly access up-to-date information, without needing to connect to the institution.
When you create a recurrent link, Belvo automatically retrieves key information about the Link ID. Once we have the information, we'll send you a historical webhook event indicating that you can make a GET request for that information.
We recommend you don't make POST calls immediately after a link is created. Instead, wait for a historical update webhook which indicates that Belvo has scraped the data and then you can make a GET request to retrieve the information (the webhook is sent soon after a link is created). If you make a GET request before you receive a historical webhook, you will receive responses with empty data fields or duplicated information.
Use of user credentials
When using recurrent links, you must ensure that you comply with the data privacy regulation of the country you operate in. Additionally, we recommend that you inform users that their credentials will be used daily in order to cyclically retrieve up-to-date data.
Refresh rates
By default, recurrent links are automatically refreshed once every seven days. However, you can change the update frequency of your recurrent links to every:
- 6 hours (four times per day)
- 12 hours (twice a day)
- 24 hours (once a day)
- 30 days (once a month)
Note: with the 30-day refresh rate, we distribute the link updates between day 1 and day 20 of the given month. The refresh date for each monthly recurrent link is initially assigned randomly between the 1st and the 20th of the month. If the following link updates are successful then the subsequent refreshes for this link will occur on the same day each month. Links are not scheduled to be updated after the 20th of the month to reserve some time for potential re-tries. For more information, check out our Help Center article on Monthly recurrent links.
Refresh rate pricing
To change your refresh rate or discuss refresh rate pricing, just email our sales team at [email protected], and they'll get right to it.
With recurrent links, we update the following information according to your chosen frequency:
Institution | Initial information | Refreshed information |
---|---|---|
Banking | All account, transaction, and owner information | - Account information, including current balance and credit data. - New transactions (added since the last recurrent link update). - Personal information of the link owner. |
Fiscal | All invoices, the tax compliance statuses, tax returns, and the tax status. | - New invoices sent or received within the last five years. - New tax returns added within the last five years. |
Single links
Single links are used to perform ad hoc data access to accounts, owners, transactions, and so on. For example, you can use it when you want to do an underwriting process to assess risk before lending money.
For single links, you need to pass the fetch_resources
parameter when creating and then listen for webhooks once the historical data has been asynchronously extracted.
Link statuses
A link can have different statuses, which reflect if the link is operational or if an action is needed to restore the link.
Status | Description | Action |
---|---|---|
valid | A valid link is a fully working link. | None ๐ |
invalid | An invalid link means that the credentials are no longer valid. | You need to ask your user to update their credentials in order for the link to be valid again. ๐กUse the Connect widget in update mode to ask your user to provide a new password. |
unconfirmed | An unconfirmed link means that the link was never created successfully. A common situation where this can occur is when a user was prompted to for an MFA token but never provided it. | You need to resume the link creation process with a token to complete the link creation. |
token_required | A token_required link means that a previously valid link now requires a new token. | You need to resume the link update process with a token. ๐กUse the Connect widget in update mode to ask your user to provide a new password. |
Checking the status of a link
You can find the status of a link by making one of the following queries and checking the value of the status field in the JSON response:
List all current links
Use the List all links method to get all the links you currently have access to. You can perform filtering on the responses to return just the links that have a certain status. In the example below, we filter the response to just have invalid links.
curl -- request POST 'https://sandbox.belvo.co/api/links/?status=invalid'\
-u [Secret Key ID]:[Secret Key PASSWORD]
curl -- request POST 'https://sandbox.belvo.co/api/links/'\
-u [Secret Key ID]:[Secret Key PASSWORD]
If you want to know about applying filters in your queries, see our Filtering responses article.
Get details for a specific link
Use the Get a link's details method to get the details for a specific Link.
curl -- request GET 'https://sandbox.belvo.co/api/links/{id}' \
-u [Secret Key ID]:[Secret Key PASSWORD]
...
{
โidโ: โc70a25d4-d8ad-9999-b59e-b8f57f0e7123",
โinstitutionโ: โliverpool_mx_retailโ,
โaccess_modeโ: โrecurrentโ,
โlast_accessed_atโ: โ2019-10-04T10:58:20.374432Zโ,
โstatusโ: โvalidโ, // Status of the link. In this case it's valid - perfect!
โcreated_byโ: โb18626ab-74aa-45fd-a66d-babf1461f962"
}
...
Where:
{id}
is the ID of the link. For example:c70a25d4-d8ad-9999-b59e-b8f57f0e7123
.
Updated 15 days ago