# Modify a link's data retrieval

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 .


Endpoint: PATCH /api/links/{id}/
Version: 1.223.0
Security: basicAuth

## Path parameters:

  - `id` (string, required)
    The  you want to change the , , or  for.
    Example: "e4bb1afb-4a4f-4dd6-8be0-e615d233185b"

## Request fields (application/json):

  - `access_mode` (string)
    The type of link to create.

- Use  to do ad hoc one-time POST requests for accounts, owners, and transactions.
- Use  to have Belvo access information on a recurrent basis so you always have fresh account, owner, balance, and transaction data.

For more information, see our Links article.
    Enum: "single", "recurrent"

  - `stale_in` (string)
    Indicates how long any user-derived data should be stored in Belvo's database for the link (both single and recurrent). For example, if you send through , Belvo will remove any data from its database relating to the user after 90 days. For more information, check out the stale_in section of our Data retention controls article.

> 📘 Info
>
> Belvo will only remove data for links that have not been updated in the period you provide in . Belvo will only remove data for links that have not been updated in the period you provide in .

By default Belvo stores user data for 365 days, unless the link is deleted.
    Example: "42d"

  - `fetch_resources` (array)
    An array of resources that you would like to receive a historical update for.

For banking institutions, you can select the following resources:
  - 
  - 
  - 
  - 
  - 
  - 
  - 
  - 
  - 


For fiscal institutions, you can select the following resources:
  - 
  - 
  - 
  - 
  - 
  - 

For employment institutions, you can select the following resources:
  - (For Mexico's IMSS and ISSTE only)
  -  (For Mexico's IMSS only)
  -  (For Brazil's INSS only)
    Example: ["ACCOUNTS","TRANSACTIONS"]

## Response 200 fields (application/json):

  - `id` (string)
    Belvo's unique identifier for the current item.
    Example: "0d3ffb69-f83b-456e-ad8e-208d0998d71d"

  - `institution` (string)
    Belvo's name for the institution.
    Example: "erebor_mx_retail"

  - `access_mode` (string,null)
    The link type.
For more information, see our Links article.
We return one of the following enum values:
  - 
  - 
  -
    Enum: "single", "recurrent", null

  - `last_accessed_at` (string,null)
    The ISO-8601 timestamp of Belvo's most recent successful access to the institution for the given link.
    Example: "2021-03-09T10:28:40.000Z"

  - `created_at` (string)
    The ISO-8601 timestamp of when the data point was created in Belvo's database.
    Example: "2022-02-09T08:45:50.406032Z"

  - `external_id` (string)
    An additional identifier for the link, provided by you, to store in the Belvo database.  include any Personal Identifiable Information (PII).  be at least three characters long.


If we identify that the identifier contains PII, we will force a  value. For more information, see our Link creation article.
    Example: "56ab5706-6e00-48a4-91c9-ca55968678d9"

  - `institution_user_id` (string)
    > 📘 Info
>
> Only applicable for links created .


A unique 44-character string that can be used to identify a user at a given institution.


📚 Check out our Avoiding duplicated links DevPortal article for more information and tips on how to use it.
    Example: "sooE7XJWEKypZJR603ecaWYk-8Ap0oD8Nr1pBQ4eG9c="

  - `status` (string)
    The current status of the link. For more information, see our Link article in the devportal.
We return one of the following values:
  - 
  - 
  - 
  -
    Enum: "valid", "invalid", "unconfirmed", "token_required"

  - `created_by` (string)
    The unique ID for the user that created this item.
    Example: "bcef7f35-67f2-4b19-b009-cb38795faf09"

  - `refresh_rate` (string,null)
    The update refresh rate for the recurrent link. For more information, check out our recurrent link documentation in our DevPortal.
We return one of the following enum values:
  - 
  - 
  - 
  -  (default)
  -  (once a month)
  -  (for single links)
    Enum: "6h", "12h", "24h", "7d", "30d", null

  - `credentials_storage` (string)
    Indicates whether or not to store credentials (and the duration for which to store the credentials).

- For recurrent links, this is set to  by default (and cannot be changed). 
- For single links, this is set to  by default.

Can be either:
  -  to store credentials (until the link is deleted)
  -  to not store credentials
  -  Any value between  and  to indicate the number of days you want the credentials to be stored.

 For more information, check out the credentials_storage section of our Data retention controls article.
    Example: "27d"

  - `fetch_resources` (array)
    An array of resources that you will receive a historical update for.
    Example: ["ACCOUNTS","TRANSACTIONS"]

  - `stale_in` (string)
    Indicates how long any user-derived data should be stored in Belvo's database for the link (both single and recurrent). For example, if you send through , Belvo will remove any data from its database relating to the user after 90 days. For more information, check out the stale_in section of our Data retention controls article.

> 📘 Info
>
> Belvo will only remove data for links that have not been updated in the period you provide in . Belvo will only remove data for links that have not been updated in the period you provide in .

By default Belvo stores user data for 365 days, unless the link is deleted.
    Example: "42d"

## Response 403 fields (application/json):

  - `code` (string)
    A unique error code () that allows you to classify and handle the error programmatically.


ℹ️ Check our DevPortal for more information on how to handle 403 access_to_resource_denied.
    Example: "access_to_resource_denied"

  - `message` (string)
    A short description of the error. 


For  errors, the description is:
  
  - .
    Example: "You don't have access to this resource."

  - `request_id` (string)
    A 32-character unique ID of the request (matching a regex pattern of: ). Provide this ID when contacting the Belvo support team to accelerate investigations.
    Example: "9e7b283c6efa449c9c028a16b5c249fb"

## Response 404 fields (application/json):

  - `code` (string)
    A unique error code () that allows you to classify and handle the error programmatically.
    Example: "not_found"

  - `message` (string)
    A short description of the error.


For  errors, the description is:

  -
    Example: "Not found"

  - `request_id` (string)
    A 32-character unique ID of the request (matching a regex pattern of: ). Provide this ID when contacting the Belvo support team to accelerate investigations.
    Example: "9e7b283c6efa449c9c028a16b5c249fb"

## Response 428 fields (application/json):

  - `code` (string)
    A unique error code () that allows you to classify and handle the error programmatically.
ℹ️ Check our DevPortal for more information on how to handle 428 token_required errors.
    Example: "token_required"

  - `message` (string)
    A short description of the error. 
For  errors, the description is:
  
  - .
    Example: "A MFA token is required by the institution to login"

  - `request_id` (string)
    A 32-character unique ID of the request (matching a regex pattern of: ). Provide this ID when contacting the Belvo support team to accelerate investigations.
    Example: "9e7b283c6efa449c9c028a16b5c249fb"

  - `session` (string)
    A 32-character unique ID of the login session (matching a regex pattern of: ).
    Example: "2675b703b9d4451f8d4861a3eee54449"

  - `expiry` (integer)
    Session duration time in seconds.
    Example: 9600

  - `link` (string)
    Unique identifier created by Belvo, used to reference the current
Link.
    Example: "30cb4806-6e00-48a4-91c9-ca55968576c8"

  - `token_generation_data` (object)
    Details on how to generate the token.

  - `token_generation_data.instructions` (string)
    Instructions for token generation.
    Example: "Use this code to generate the token"

  - `token_generation_data.type` (string)
    Type of the data to generate the token (QR code, numeric
challenge).
    Example: "numeric"

  - `token_generation_data.value` (string)
    Value to use to generate the token.
    Example: "12345"

  - `token_generation_data.expects_user_input` (boolean)
    Indicates whether the user needs to provide input in order to complete the authentication.
When set to , your user may need to:
- confirm the login on another device
- scan a QR code
You will still need to make a PATCH call to complete the request.
    Example: true

## Response 500 fields (application/json):

  - `code` (string)
    A unique error code () that allows you to classify and handle the error programmatically.


ℹ️ Check our DevPortal for more information on how to handle 500 unexpected_error errors.
    Example: "unexpected_error"

  - `message` (string)
    A short description of the error. 


For  errors, the description is:
  
  - .
    Example: "Belvo is unable to process the request due to an internal system issue or to an unsupported response from an institution"

  - `request_id` (string)
    A 32-character unique ID of the request (matching a regex pattern of: ). Provide this ID when contacting the Belvo support team to accelerate investigations.
    Example: "9e7b283c6efa449c9c028a16b5c249fb"