Link creation best practices
Links are the fundamental connection between your user, Belvo, and an institution. As such, it's probably a good idea to make sure you get the process right 🤓. In this article, we'll cover some best practices in your link creation process, as well as tips and tricks on how to handle other events.
Link creation flow
When you're setting up your link creation flow:
- Make sure you first register your users with your platform.
- Use the Connect Widget to create your links.
- Store the received
link_id
in your database.
Why should you first register a user in your platform and then use the widget?
By first registering your user in your platform, you have a way to associate a user with a created link in your database.
Orphan links
An orphan link is a link that was created but has not been associated with a user in your database.
Orphan links can occur when:
- you do not register your user first with your platform.
- your user closes your application (mobile or browser) during a successful connection process.
To recover orphan links created due to the user closing your application, we recommend using the external_id
parameter as an additional identifier for your link in Belvo's database.
Adding your own identifier
You can use the optional external_id
parameter when creating a new link to provide an additional unique identifier within the Belvo system. This is particularly useful as you can later make a request to Belvo's Links endpoint and filter for all the links associated to an external_id
.
By using external_id
and filtering, you can:
- list all the links related to a user.
- get the latest status of each link, and if needed, prompt the user to update their token or their credentials for an institution.
- identify any orphan links for that user and then associate the
link_id
in your database.
The external_id
that you provide:
- should be a unique ID for each user in your database.
- must be at least three characters long.
- can only be composed of letters, numbers, dashes (
-
), and underscores (_
). - cannot contain any personally identifiable information about the user (email, name, phone number, credit card number, and so on).
Personally identifiable information with
external_id
If you use any personally identifiable information in your
external_id
, Belvo will set theexternal_id
tonull
. As such, you will not be able to filter your links by thatexternal_id
.
Tips for using external_id
To use the optional external_id
parameter, we highly recommend the following flow:
- Register your users first with your platform and create a unique ID for that user in your database.
- Use the unique ID as the value of the
external_id
parameter when creating a link. - Use the Connect Widget to create your links.
Then, as required, you can periodically call /links/?external_id={user's unique ID in your system}
and identify any orphan links or links that need to have their status updated.
Code examples for starting the widget or filtering responses by external_id
For examples of how to start the widget with the
external_id
parameter, see our Widget startup configuration article.For examples of how to filter your response by
external_id
, see our Filtering responses article.
Avoiding duplicated links
Duplicated links occur when:
- the user tries to connect their account to the same institution with the same credentials a second time.
- you are not storing the
link_id
in your database. - the user closes your application (mobile or browser) during a successful connection process.
To help you avoid link duplication, have a look at our helpful tips below.
Tip #1 - Register your users first
Make sure that you register your user with your platform first. This way, you will always have a way to associate created links with a user in your database and keep track of what accounts they have already connected.
Tip #2 - Use external_id
When your user starts a new session on your platform:
-
Request all links associated for the user:
/links/?external_id={user's unique ID in your system}
. -
Associate any orphan links that have
status=valid
with your user in your database and let your user know that the link was created successfully.
If the status of the link is not valid
, you can either:
- delete the link and request the user to connect their account again.
- update the status of the link using Widget Update Mode.
This way, you will ensure that you will not have any orphan links and that all the links associated with a user have a valid
status.
Tip #3 - Use the widget’s callback metadata
After receiving the Success callback from the widget, you can use the link
ID to retrieve information about the link. The information from the link can then be compared to the existing links that this user already created in your database (Tips #1 and #2) and utilize this to detect potential duplicates. For example, you can compare a combination of the account’s institution_id
, account name
, and account number
to determine whether your user has previously linked an account to your application.
Tip #4 - Show already-connected accounts
Before your users open the widget, in your UI, display a list of accounts that they have already connected (to find all the accounts they have, you can use the external_id
in combination with the metadata you receive from the Widget in Tip #3). By showing this information, your users will avoid linking the same account again (and you avoid duplicated Links).
Tip #5 - Use institution_user_id
to keep track of links
Only applicable for links created after 08-02-2022.
When your user connects their account, we return the institution_user_id
, which is a unique 44-character string that can be used to identify a user at a given institution. You can use this identifier to compare in your database whether or not your user has previously connected this account, and if you want to avoid duplicated links, you can choose to replace the existing link.id
in your database.
Example:
- Your user connects their account to an institution and you receive the following link
id
andinstitution_user_id
:
{
"id": "link-id-1",
"institution_user_id": "ooE7XJWEKypZJR603ecaWYk-8Ap0oD8Nr1pBQ4eG9c="
}
- Your user connects the same account again using the same credentials and you receive:
{
"id": "link-id-2",
"institution_user_id": "ooE7XJWEKypZJR603ecaWYk-8Ap0oD8Nr1pBQ4eG9c="
}
- Comparing the
institution_user_id
in your database, you see that this is the same account. If you would prefer to not have duplicated links in your database, you can replace thelink-id-1
withlink-id-2
in your database and uselink-id-2
for your future requests.
Opt-in to prevent duplicate links
Belvo offers an opt-in feature designed to prevent duplicated links from being created, ensuring that your users never connect the same account twice to your application. If your user has already successfully connected their account and they try to connect the same account again:
- Integrations using Belvo's Connect Widget - your users will receive an error in the Connect Widget and your backend will receive an Error Event Callback.
- Integrations not using Belvo's Connect Widget - you will receive a 400 duplicated API error.
Links with
unconfirmed
statusIn the situation where your user has previously attempted to create a link but never finished the flow (resulting in the link
status
being set tounconfirmed
), when they try to connect the same account again Belvo will allow for the link to be created.This feature ensures that you can still retrieve vital user information and provides your users' the ability to still connect their accounts.
If you'd like to opt-in for this feature, just contact our support team and they'll gladly help you out!
In order to use this feature, you may be required to alter your integration to use the
external_id
parameter on link creation.
Updated 7 months ago