Sign in

v1

latestOpenAPI 3.0.22026-08-061464031.4 MB
Links

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

patch/api/links/{id}/

Path parameters

idstring uuid required
Example:e4bb1afb-4a4f-4dd6-8be0-e615d233185b

The link.id you want to change the access_mode, stale_in, or fetch_resources for.

Request body

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 <a href="https://developers.belvo.com/docs/links-and-institutions#links" target="_blank">Links</a> article.

stale_instring

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 <a href="https://developers.belvo.com/docs/data-retention-controls#stale_in" target="_blank">stale_in</a> 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_resourcesstring[]

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)

Example request

{
  "stale_in": "42d",
  "fetch_resources": [
    "ACCOUNTS",
    "TRANSACTIONS"
  ]
}

Response

Ok

idstring uuid

Belvo's unique identifier for the current item.

institutionstring

Belvo's name for the institution.

access_mode'single' | 'recurrent' | 'null' nullable

The link type. For more information, see our <a href="https://developers.belvo.com/docs/links-and-institutions#links" target="_blank">Links</a> article. We return one of the following enum values:

  • single
  • recurrent
  • null
last_accessed_atstring date-time nullable

The ISO-8601 timestamp of Belvo's most recent successful access to the institution for the given link.

created_atstring date-time

The ISO-8601 timestamp of when the data point was created in Belvo's database.

external_idstring

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 <a href="https://developers.belvo.com/docs/link-creation-best-practices#adding-your-own-identifier" target="_blank">Link creation article</a>.

institution_user_idstring

📘 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 <a href="https://developers.belvo.com/docs/link-creation-best-practices#avoiding-duplicated-links" target="_blank">Avoiding duplicated links</a> 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 <a href="https://developers.belvo.com/docs/links-and-institutions#links" target="_blank">Link</a> article in the devportal. We return one of the following values:

  • valid
  • invalid
  • unconfirmed
  • token_required
created_bystring 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 <a href="https://developers.belvo.com/docs/links-and-institutions#recurrent-links" target="_blank">recurrent link documentation</a> 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_storagestring

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 <a href="https://developers.belvo.com/docs/data-retention-controls#credentials_storage" target="_blank">credentials_storage</a> section of our Data retention controls article.

fetch_resourcesstring[]

An array of resources that you will receive a historical update for.

stale_instring

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 <a href="https://developers.belvo.com/docs/data-retention-controls#stale_in" target="_blank">stale_in</a> 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.

Example response

{
  "id": "0d3ffb69-f83b-456e-ad8e-208d0998d71d",
  "institution": "erebor_mx_retail",
  "access_mode": "recurrent",
  "last_accessed_at": "2021-03-09T10:28:40.000Z",
  "created_at": "2022-02-09T08:45:50.406032Z",
  "external_id": "56ab5706-6e00-48a4-91c9-ca55968678d9",
  "institution_user_id": "sooE7XJWEKypZJR603ecaWYk-8Ap0oD8Nr1pBQ4eG9c=",
  "status": "valid",
  "created_by": "bcef7f35-67f2-4b19-b009-cb38795faf09",
  "refresh_rate": "7d",
  "credentials_storage": "27d",
  "fetch_resources": [
    "ACCOUNTS",
    "TRANSACTIONS"
  ],
  "stale_in": "42d"
}