# Links

A **Link** is a set of credentials associated to an end-user's access to an **institution**. You will need to register a **Link** before accessing information from that specific end-user, such as account or transaction details.

We recommend using the Belvo Hosted Widget to manage the connection process.

## List links

 - [GET /api/links/](https://developers.belvo.com/apis/belvoopenapispec/links/listlinks.md): ## ▶️ Usage

With the List Links method, you can:

1. List all links elated to your Belvo account (without using any query parameters).
2. Get the details of a specific  (using the  query parameter).

## 📖 Pagination

This method returns a paginated response (default: 100 items per page). You can use the  query parameter to increase the number of items returned to a maximum of 1000 items. You can use the  query parameter to navigate through the results. For more details on how to navigate Belvo's paginated responses, see our Pagination Tips article.

## 🔦 Filtering Responses

Please see the query list below for a list of fields that you can filter your responses by. For more information on how to use filters, see our Filtering responses article.


## Register a new link

 - [POST /api/links/](https://developers.belvo.com/apis/belvoopenapispec/links/registerlink.md): ## ▶️ Usage

Register a new link (a connection between your user and their institution) using the Belvo API.

> 👍 We really recommend using our Connect Widget to handle link creation and link status updates.

To make things easier, we've included custom examples for the links you can create for each of our products. Just click on the type of link you want to create in the  section below.


## Complete a links request

 - [PATCH /api/links/](https://developers.belvo.com/apis/belvoopenapispec/links/patchlinks.md): Used to resume a Link register session that was paused because an MFA token
was required by the institution.


## Get a link's details

 - [GET /api/links/{id}/](https://developers.belvo.com/apis/belvoopenapispec/links/detaillink.md): Get the details of a specific link.

## Modify a link's data retrieval

 - [PATCH /api/links/{id}/](https://developers.belvo.com/apis/belvoopenapispec/links/modifylinkdataretrieval.md): Modify the data retrieval settings for a specific link. At present you can:

  - Change a link's access mode from  to  or from  to .
  - Modify they  period for the link.
  - Modify the historical resources you want to retrieve for the link ().

## Changing a link's 
  
When you change a link from  to , the next day a historical update of the core resources for the link is triggered (resulting in you receiving  webhooks for the link). You are billed for these historical updates.

## Modifying 

If you only modify the  period for a link, this will not trigger a historical update. In order to trigger a historical update for the link, you must change the .

## Modifying 
  
If you only modify the  for a link, this will not trigger a historical update. In order to trigger a historical update for the link, you must change the .


## Update a link's credentials

 - [PUT /api/links/{id}/](https://developers.belvo.com/apis/belvoopenapispec/links/updatelink.md): Update the credentials of a specific link. If the successfully updated link is a recurrent one, we automatically trigger an update of the link. If we find fresh data, you'll receive historical update webhooks.

> 👍 Use our Connect Widget
>
>  We recommend using our Connect Widget to handle updating invalid or token_required links.


## Delete a link

 - [DELETE /api/links/{id}/](https://developers.belvo.com/apis/belvoopenapispec/links/destroylink.md): Delete a specific link and all the associated data (for example: transactions, accounts, invoices, tax returns, employments, and so on) for that link from your Belvo account. This action is irreversible, and you will not be able to recover the deleted data.

{% admonition type="success" name="Use the X-Belvo-Request-Mode: async header" %}
  We highly recommend setting the  header to  to enable asynchronous deletion. This way, you will avoid the rate limit of 5 deletions per minute. When set, the endpoint will respond with a  status and provide a request ID for tracking the deletion process. Once the process is complete, you will receive a  webhook notification.
  
  If you do not set this header, the endpoint will respond with a  status, but you will be subject to the rate limit of 5 deletions per minute. If you exceed this limit, you will receive a  error.
{% /admonition %}


## Trigger a historical update for a link

 - [POST /api/links/{id}/refresh/](https://developers.belvo.com/apis/belvoopenapispec/links/refreshhistoricaldataforlink.md): {% admonition type="warning" name="Concurrent Request Limit" %}
  To prevent duplicate requests, this endpoint has a 10-minute cooldown period per link. If you attempt to refresh the same link within 10 minutes of a previous request, you will receive a  error with the message .
{% /admonition %}

Use this method to trigger a historical update for a specific link (single or recurrent). Use the  parameter to specify which resources you want to update. If you do not specify this parameter, the historical update will be performed for all resources supported by the institution that the link is associated with.

On a successful request, our API will respond with a  status code and a  that you can later use to associate a given  webhook to this request.

{% admonition type="info" name="Does not update link definition" %}
  This endpoint does not update the link definition itself, only the historical data for the specified resources. If you want to change the link's  permanently, you should use the  method instead.
{% /admonition %}