So, want to get started using Belvo? We've got you covered. Over the next few sections, we'll get you set up with API keys, a Postman collection, and run you through a simple flow with our API so you can see how easy it is to access a whole world of information!

Prerequisites

In this getting started guide, we make use of two pieces of software that you should create free accounts for:

• Postman
• Pipedream

Once you create these accounts, you can go ahead with this guide!

Create a Belvo account

To get started with Belvo, you need to create a Belvo account and generate your API keys.

1. Go to the Belvo signup page and fill in the required fields.

2. Check your inbox for an email from us and confirm your email address.
   The subject line will be: [Belvo] Please Confirm Your Email Address

✳️ Awesome! Once you click on the link in the email, you'll be redirected to the Belvo dashboard! In the dashboard, you can set up your account, check your activity logs, and generate your Belvo API keys.

Generate your API keys and fork Postman collection

Now that you have an account - let's generate some API keys to start working with Belvo.

📘

Belvo environments

Belvo offers two environments:

• Sandbox: a test environment with dummy data that you can use for unlimited development and testing.
• Production:a live environment used with real connections to institutions. If you would like access to our Production environment, you will need to contact our support team so that we can get you all set up.

For each environment, you need separate API keys.

To generate your API keys:

1. In the Sandbox environment, go to the Developers - API Keys tab of the dashboard. We recommend that you use the sandbox environment to play around with our API.

2. Click on Generate API Keys, which will automatically generate your API keys.

   

3. In the pop-up, click the Run in Postman button. This will automatically fork our Postman Collection to your private workspace and populate the secretId and secretPassword.

   

   🚧

   For security reasons, we only show the secretPassword once in the dashboard after the generation. Make sure you store it securely to be able to retrieve it later. If you lose your secretPassword, you will need to reset your API keys.

4. You will be redirected to Postman will need to:

   1. Give a name to the fork, such as My_First_Belvo_Fork.

   2. Select in which workspace the collection should be saved to (by default, you should select My Workspace).

   3. Click Fork collection.

      

✳️ Done! Belvo's postman collection will be copied into your workspace and you will be able to easily make API calls to retrieve information!

👍

Postman Environments

When you fork the collection, Belvo automatically creates the Postman environment for you with the baseUrl, secretId, and secretPassword. Then, when you want to use our API, just look for an environment that starts with Belvo - sandbox (xxx).

📘

Already got API keys and just want the collection?

If you already have your API keys and just want to fork our collection, simply click the Run in Postman button below! (Note the link below does not open in a separate tab. We recommend you use Ctrl / Cmd and click on the link to open in a new tab.)

Test that it works!

Just to make sure you have set everything up correctly, let's make sure that you can list all the institutions in our Sandbox environment.

1. Make sure that you select your Belvo - sandbox (xxx) environment.
2. Go to Belvo API Docs → Core Aggregation Resources → Institutions → Get List all institutions.
3. Click Send.
4. If everything is correctly set up, you should see a whole host of institutions appear!

✳️ And you're done! Now, let's set up Pipedream!

Add your Belvo API keys to Pipedream

To add your Belvo API keys to Pipedream:

1. Log in to your Pipedream account.

2. Go to Settings - Environment Variables.

3. Click New Variable and in the pop-up window

   1. For the Key, enter secretIdSandbox.

   2. For the Value, enter the Belvo secretId you generated in your dashboard.

   3. For the Description, enter My Sandbox Belvo secretId.

   4. Check the Configure as secret box.

   5. Click Create.

      

4. Click New Variable again and in the pop-up window

   1. For the Key, enter secretPasswordSandbox.

   2. For the Value, enter the Belvo secretPassword you generated in your dashboard.

   3. For the Description, enter My Sandbox Belvo secretPassword.

   4. Check the Configure as secret box.

   5. Click Create.

      

✅ Done! Now when we fork Belvo's Webhook Workflow, your API keys will automatically be added to any flow.

Forking Belvo's Webhook Workflow

To fork Belvo's Webhook Workflow:

1. Click on this link to fork the workflow: Fork Belvo Webhook Worklow.
2. Provide a Project Name, such as Belvo_Integration_Sandbox, and click Create project and continue.
3. Provide a Workflow Name, such as Belvo_Webhook_Workflow_Sandbox, and click Create Workflow.

❇️ Done! You now have Belvo's Webhook Workflow in your Pipedream account. Now we just need to do generate the Webhook URL so that you can add it to your Belvo account!

Generate the Webhook URL

To generate the Webhook URL for the Belvo Webhook Workflow:

1. In the workflow:

   1. Click on the trigger (first item in the workflow).
   2. In the right-hand pop-up, click Save and continue.
   

2. Copy the generated webhook URL and save it.

3. Click Deploy.

   

❇️ Done! You now have a webhook URL that you can add to your Belvo account!

Adding the webhook URL to Belvo

So now that you've created a Webhook URL, let's add it to your Belvo account:

1. Sign in to your Belvo Dashboard.

2. Choose the Sandbox environment. For initial testing, and throughout this guide, we use the Sandbox environment.

3. Go to Developers -> Webhooks.

4. Click +New webhook.

5. Fill in the New webhook form with the required information.

   1. URL: the URL to receive the webhook notifications.
   2. Authorization: an optional bearer token to use if your URL is protected.

6. Click Create webhook.

   

✅ Done! You've now created a webhook and can start creating links and receiving events!

Testing the flow

So now that we have everything set up, we can test the flow to make sure everything is running smoothly!

1. In Postman, make sure you select your Belvo Sandbox environment.

2. Go to Belvo API Docs -> Core Aggregation Resources -> Links -> Register a new link.

3. In the Body tab, copy and paste the following code:

   Create a link in Postman example

   {
       "institution": "planet_mx_employment",
       "username": "BLPM951331IONVGR54",
       "external_id": "getting_started_link",
       "access_mode": "single",
       "fetch_resources": ["OWNERS", "EMPLOYMENT_RECORDS"]
   }
   

4. Click Send.

   

Now in Pipedream, go to the Belvo_Webhook_Workflow_Sandbox and see the magic happen! (Note, the first time you run this flow the webhook might take a minute or two to arrive as Belvo performs validation on the URL).

Once you see webhook events coming in, you can click on them and in the right-hand panel, scroll down to see your data!

✅ And that's it! You have just created a webhook flow and can retrieve data from Belvo asynchronously. That's fantastic! You can use this flow with any of our aggregation or enrichment products:

• Banking
• Employment
• Fiscal
• Enrichment