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:

  1. Make sure you first register your users with your platform.
  2. Use the Connect Widget to create your links.
  3. Store the received link_id in your database

Basic flow for link creation

👍

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.

Flowchart of an orphan link created in

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 linksorphan links - An orphan link is a link that has not been associated with a user in your database. 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.
  • 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 the external_id to null. As such, you will not be able to filter your links by that external_id.

Tips for using external_id

To use the optional external_id parameter, we highly recommend the following flow:

  1. Register your users first with your platform and create a unique ID for that user in your database.
  2. Use the unique ID as the value of the external_id parameter when creating a link.
  3. 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.

Using external_id in your link creation flow

📘

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.

Duplicated links

You can receive a duplicated link error 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 manage these errors, 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 or you receive a duplicated_link error:

  1. Request all links associated for the user: /links/?external_id={user's unique ID in your system}.

  2. Associate any orphan linksorphan links - An orphan link is a link that has not been associated with a user in your database. 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.


Did this page help you?