--- title: "Modify a link's data retrieval" method: PATCH path: "/api/links/{id}/" tags: ["Links"] --- # Modify a link's data retrieval `PATCH /api/links/{id}/` 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`. ## Path parameters - `id` string, uuid, required ## Request body - ChangeAccessMode โ€” Request body to change the access mode, stale_in, or fetch_resources of a link. - `access_mode` 'single' | 'recurrent' โ€” The type of link to create. - Use `single` to do ad hoc one-time POST requests for accounts, owners, and transactions. - Use `recurrent` 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. - `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 `90d`, 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 `stale_in`. Belvo will only remove data for links that have not been updated in the period you provide in `stale_in`. By default Belvo stores user data for 365 days, unless the link is deleted. - `fetch_resources` string[] โ€” An array of resources that you would like to receive a historical update for. For banking institutions, you can select the following resources: - `ACCOUNTS` - `OWNERS` - `TRANSACTIONS` - `BILLS` - `INVESTMENTS` - `INVESTMENT_TRANSACTIONS` - `INCOMES` - `RECURRING_EXPENSES` - `RISK_INSIGHTS` For fiscal institutions, you can select the following resources: - `FINANCIAL_STATEMENTS` - `INVOICES` - `TAX_COMPLIANCE_STATUS` - `TAX_RETENTIONS` - `TAX_RETURNS` - `TAX_STATUS` For employment institutions, you can select the following resources: - `EMPLOYMENT_RECORDS`(For Mexico's IMSS and ISSTE only) - `EMPLOYMENT_METRICS` (For Mexico's IMSS only) - `EMPLOYMENTS` (For Brazil's INSS only) ## Response `200` Ok - Link - `id` string, uuid โ€” Belvo's unique identifier for the current item. - `institution` string โ€” Belvo's name for the institution. - `access_mode` 'single' | 'recurrent' | 'null', nullable โ€” The link type. For more information, see our Links article. We return one of the following enum values: - `single` - `recurrent` - `null` - `last_accessed_at` string, date-time, nullable โ€” The ISO-8601 timestamp of Belvo's most recent successful access to the institution for the given link. - `created_at` string, date-time โ€” The ISO-8601 timestamp of when the data point was created in Belvo's database. - `external_id` string โ€” An additional identifier for the link, provided by you, to store in the Belvo database. **Cannot** include any Personal Identifiable Information (PII). **Must** be at least three characters long. If we identify that the identifier contains PII, we will force a `null` value. For more information, see our Link creation article. - `institution_user_id` string โ€” > ๐Ÿ“˜ Info > > Only applicable for links created **after 08-02-2022**. 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. - `status` 'valid' | 'invalid' | 'unconfirmed' | 'token_required' โ€” The current status of the link. For more information, see our Link article in the devportal. We return one of the following values: - `valid` - `invalid` - `unconfirmed` - `token_required` - `created_by` string, uuid โ€” The unique ID for the user that created this item. - `refresh_rate` '6h' | '12h' | '24h' | '7d' | '30d' | 'null', nullable โ€” 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: - `6h` - `12h` - `24h` - `7d` (default) - `30d` (once a month) - `null` (for single links) - `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 `store` by default (and cannot be changed). - For single links, this is set to `365d` by default. Can be either: - `store` to store credentials (until the link is deleted) - `nostore` to not store credentials - Any value between `1d` and `365d` 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. - `fetch_resources` string[] โ€” An array of resources that you will receive a historical update for. - `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 `90d`, 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 `stale_in`. Belvo will only remove data for links that have not been updated in the period you provide in `stale_in`. By default Belvo stores user data for 365 days, unless the link is deleted. ## Other responses - `400` โ€” Bad request error - `401` โ€” Unauthorized - `403` โ€” Access to Belvo API denied - `404` โ€” Not Found Error - `428` โ€” MFA Token Required - `500` โ€” Unexpected Error --- [API](https://skmtc.net/belvo/apis/belvo-api-docs.md) ยท [All operations](https://skmtc.net/belvo/apis/belvo-api-docs/llms.txt) ยท [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/belvo/belvo-api-docs/versions/3423c786ece5/schema)