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.
  • gig institution, such as Uber or Rappi.

You can see a complete list of banking institutions by either consulting our Institutions page, or querying the following endpoint:

Endpoint

Method

Description

List

GET

List of all institutions currently supported by Belvo.

Detail

GET

Get the details for a specific institution.

Links

Whenever an end user connects to their institution using the Belvo API, we create a Link. The Link is a set of credentials, for example the username and password, that is associated with an end 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 endpoint:

Endpoint

Method

Description

Register

POST

Register a new link from a financial institution to your Belvo account.

List

GET

List of all links currently associated with your Belvo account.

Resume

PATCH

Resume a link registering session that was paused because a 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.

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 have to perform POST calls to an institution every time you want to access fresh data.

Recurrent links

With recurrent links, Belvo automatically refreshes information daily 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.

Recurrent link flow

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 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 the historical webhook and make a GET request to retrieve the information. If you make a GET request before you receive a historical webhook, you will receive responses with empty data fields.

❗️

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.

👍

By default, recurrent links are automatically refreshed once a day every 24 hours.
However, you can contact us to change the update frequency of your recurrent Links to every:

  • 6 hours (four times per day)
  • 12 hours (twice a day)

Institution

Initial information

Refreshed information

Banking

All accounts, transactions, and owner information

  • Account information, including current balance and credit data.

  • New transactions (added within the last 365 days).

  • 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.

Gig economy

All accounts, transactions, and owner information

  • New transactions (added within the last 365 days).

  • Personal information of the link owner.

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 token was needed and never provided by the user.

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 Link List method to get all the links you currently have access to. You can perform filtering on the responses so as 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 Link Detail 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.

What next

Now that you're caught up on institutions and links, check out our articles on:

Updated 25 days ago


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.

Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.