Belvo offers mechanisms to let you control the data that is retained regarding your users. These mechanisms are divided into two levels:

• Link level
• Resource level

Link-level data retention controls

When creating a link, you can set parameters that define how Belvo stores:

• Encrypted credentials (credentials_storage)
• User-derived data (stale_in)

credentials_storage

The credentials_storage parameter controls how long Belvo will store the encrypted credentials in our database. You can set the following values:

With nostore or 1d-365d, once the period has expired the link status will change to invalid. If you need to retrieve additional information about your user, you will need to ask them to create the link again.

📘

After you create the link you cannot update the values for credentials_storage. You will need to delete the link and if necessary ask your user to connect again.

stale_in

The stale_in parameter controls how long Belvo stores user-derived data. The period is relative to the link’s last_updated_at (the last time that the user’s account was accessed) timestamp. You can set the following values:

📘

stale_in only controls the deletion of the data associated with a user. To delete the link, you need use our Delete a link request.

Resource-level data retention controls

save_data

Whenever you make a POST call to retrieve data about a user, you can choose whether or not Belvo stores any user-derived data using the save_data parameter. You can set the following values:

Use cases

PFMs and ERPs

PFMs and ERPs need recurrent access to information (both current and historical) in order to provide clients with a detailed overview of their accounts, balances, and transactions. For this use case, we recommend using recurrent links with the default data retention controls:

// Default credentials and user-derived data storage
{
    "access_mode": "recurrent",
    "credentials_storage": "store", // Default
    "stale_in": "365d", // Default
}

Unless the recurrent link’s status is invalid or token_required, you will continue to be able to retrieve historical data for over 365 days.

Recurring credit assessments and short-term loans

With recurring credit assessments or short-term loans, you most likely want to only store data for a limited amount of time so that you can follow your user’s account balances and payments for the duration of the loan. For this case, we recommend using single links where you only store credentials and user-derived data for the duration of the loan:

// Store credentials and data for a limited period
{
    "access_mode": "single",
    "credentials_storage": "100d",
    "stale_in": "100d",
    "fetch_resources": ["ACCOUNTS", "OWNERS", "TRANSACTIONS"]
}

📘

All user-derived data will be stored in our database relative to the link’s last_accessed_at timestamp. For example, if you create a link on the first day of the month and then make a POST call to retrieve data on the 10th day of the month, we store the user-derived data for 21 days after that day.

Compliance requirements

For companies that are required to undergo routine audits or compliance checks, you might not want to store sensitive data any longer than absolutely necessary. For this case, we recommend using single links with minimal data storage:

// Store only the necessary data for audit or compliance
{
    "access_mode": "single",
    "credentials_storage": "3d",
    "stale_in": "2d",
    "fetch_resources": ["ACCOUNTS", "BALANCES", "TRANSACTIONS"]
}

📘

In this case, the credentials will be voided after three days, however, the user-derived data will still be present in Belvo’s system until two days have passed after the link’s last_updated_at timestamp.

ID verification or credit assessments

In the case that you want to use Belvo for ID verification or one-off credit assessments, you won’t need to access user-derived data at a later date. For this case, we recommend using single links where you do not store credentials and have a minimal user-derived data storage:

// Do not store credentials or user-derived data
{
    "access_mode": "single",
    "credentials_storage": "nostore",
    "stale_in": "1d",
    "fetch_resources": ["ACCOUNTS", "OWNERS", "TRANSACTIONS"]
}

Once the link is created, you need to wait for the historical_update webhook for each of the resources you list. You can then retrieve the user-derived data using a GET call.

📘

The user-derived data will be removed from our database one day later.

FAQ

Can recurrent links have a defined credential storage time range?

For recurrent links, credentials_storage must be set to store. If you would like to remove the link (and any user-derived data associated with the link), you need to use the Delete a link request.

How does stale_in work for recurrent links?

With recurrent links, once a link status is set to invalid or token_required we are no longer able to access the user’s institution. As such, the link’s last_accessed_at timestamp will not be updated and Belvo will delete any user-derived data once the stale_in period is met.

Does Belvo delete user-derived data by default for recurrent links?

In the case that the last_accessed_at timestamp has not been updated for 365 days, Belvo will automatically remove any user-derived data relating to the link.

Can I change the link’s credentials_storage or stale_in values?

After you create the link you cannot update the values for credentials_storage or stale_in. You will need to delete the link and ask your user to connect again.

Can I update a link’s credentials if it is still within the storage period?

Yes, if the storage period has not yet expired, you can update the credentials or provide an MFA token using our Update a link’s credentials request.

👍

If you’re using recurrent links, you’ll receive information that a link needs to be updated via our Links webhooks.

If I delete a link, does all the associated user-derived data also get deleted?

Yes, once you delete a link, Belvo will remove any data (including credentials) associated with the user.

Does Belvo store any data when from the Enrich Your Own Data suite of resources?

No, Belvo does not store any data when you use our Enrich Your Data Data resources.

I forgot to use save_data: false when I made a POST call. How do I remove the data from Belvo’s database?

To remove any resource data, just use the resource’s Delete a {resource name} request. For example, if you retrieved account information, you can use the Delete an account request.

How does Belvo encrypt credentials?

Belvo uses industry-standard AES-256 symmetric encryption to encrypt credentials. We also provide an additional layer of security when you use Belvo’s Connect Widget where we encrypt the user’s credentials first at the widget level using RSA 2048 asymmetric encryption.