# 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 link.id (using the id query parameter).

## 📖 Pagination

This method returns a paginated response (default: 100 items per page). You can use the page_size query parameter to increase the number of items returned to a maximum of 1000 items. You can use the page 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 Body Params 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 single to recurrent or from recurrent to single.
  - Modify they stale_in period for the link.
  - Modify the historical resources you want to retrieve for the link (fetch_resources).

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

## Modifying stale_in

If you only modify the stale_in 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 access_mode.

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

## 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 X-Belvo-Request-Mode header to async 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 202 Accepted status and provide a request ID for tracking the deletion process. Once the process is complete, you will receive a link_deleted webhook notification.
  
  If you do not set this header, the endpoint will respond with a 204 No Content status, but you will be subject to the rate limit of 5 deletions per minute. If you exceed this limit, you will receive a 429 Too Many Requests 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 409 Conflict error with the message "The link has already been refreshed. Please wait X minutes before trying again.".
{% /admonition %}

Use this method to trigger a historical update for a specific link (single or recurrent). Use the fetch_resources 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 202 status code and a request_id that you can later use to associate a given historical_update 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 fetch_resources permanently, you should use the Modify a link's data retrieval method instead.
{% /admonition %}