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!

Get your Belvo API keys

Let's get you some API keys so you can start using Belvo 🤓.

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

Create a Belvo account

1. Go to the Belvo Dashboard sign up 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 collection

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

📘

Belvo environments

Belvo offers three environments:

Sandbox - a test environment with dummy data that you can use for unlimited development and testing.
Development - a test environment where you can test with real credentials and institutions, limited to 25 links.
Production - a live environment used with real connections to institutions

For each environment, you need separate API keys.

To generate your API keys:

1. In the Sandbox environment, select the go to the 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'll need to reset your API keys.

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

   1. Give a name to the 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, simple click the Run in Postman button below!

Test that it works!

Just to make sure you've set everything up correctly, let's see 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 make our first calls to the Belvo API!

Extract your first financial data

API keys? Check! Postman? Check! All that's left is to get some data!👩‍💻

Now that you have your API keys and Postman collection set up, let's run through a simple flow of calls that you can make and the data that you can interact with.

What you'll do is:

1. Register a link between a user and a banking institution.
2. Retrieve all the account information for that link.
3. Retrieve the transactions available for that link.

👍

We'll be using our Sandbox environment to run through this flow. So make sure that you've generated your Sandbox keys!

Let's get started!

Register a link

Your end users will need to connect to their account via the Belvo API (we strongly recommend you check out our Connect Widget article to see how we can make the process easier and quicker for you). When they connect their account, we generate a Link ID that you'll need to use whenever you want to access specific information about that end user.

{
    "institution": "{institution_name}",
    "username": "{bank_username}",
    "password": "{bank_password)"
}

curl -X POST \
  https://sandbox.belvo.com/api/links/ \
  -H 'Content-Type: application/json' \
  -H 'Host: sandbox.belvo.com' \
  -d '{
    "institution": "{institution_name}",
    "username": "{bank_username}",
    "password": "{bank_password)"
  }' \
  -u Secret-Key-ID:Secret-Key-PASSWORD

Where:

• {institution_name} is the institution name. For example: erebor_mx_retail.
• {bank_username} is the end user's banking login username. For example: bnk100.
• {bank_password) is the end user's password. For example: full.

If you enter everything correctly, in Postman you'll see the following 201 response:

{
  "id": "cb65f82c-dc93-4d3e-8270-9a27528397f5", // You'll need store this value somewhere for future calls.
  "institution": "erebor_mx_retail", // The institution the link is registered with.
  "access_mode": "recurrent", // The link type.
  "last_accessed_at": "2019-10-30T12:39:18.014131Z", // Date when the link was created.
  "status": "valid", // The status of the link.
  "refresh_rate": "7d", // How often Belvo will refresh the data for the link
  "created_by": "6e9be884-4781-4143-b673-aca02475ee8c", // Unique ID of the user that created the link
  "external_id": null, // Optional field that you can provide in your request for internal purposes
  "created_at": "2023-03-21T16:18:38.430608Z", // When the link was created
  "institution_user_id": "B8UJssxhw_LF92QxX5CrlytYiwjFmi1iKbsMnGJ4nms=" // Unique ID of the username + institution that you can use to prevent duplicates
}

Request all account information

After we have registered a link, you can now make some requests specific to that link, for example, account information. Try the following call to get all the accounts connected with a Link ID.

{
    "link": "{link_id}"
}

curl -X POST \
  https://sandbox.belvo.com/api/accounts/ \
  -H 'Content-Type: application/json' \
  -H 'Host: sandbox.belvo.co' \
  -H 'cache-control: no-cache' \
  -d '{
    "link": "{link_id}"
}' \
  -u Secret-Key-ID:Secret-Key-PASSWORD

Where:

• {link_id} is the ID of the link you previously created. For example: cb65f82c-dc93-4d3e-8270-9a27528397f5.

In Postman, you should see a response similar to this one. For detailed information on the account fields returned, make sure to check out our Accounts API reference documentation.

Retrieve all transactions

Next, let's retrieve all the transactions associated with the link.

{
    "link": "{link_id}",
    "date_from": "{date1}",
    "date_to": "{date2}"
}

curl -X POST \
  https://sandbox.belvo.com/api/transactions/ \
  -H 'Content-Type: application/json' \
  -H 'Host: sandbox.belvo.com' \
  -H 'cache-control: no-cache' \
  -d '{
    "link": "{link_id}",
    "date_from": "{date1}",
    "date_to": "{date2}"
}' \
  -u Secret-Key-ID:Secret-Key-PASSWORD

Where:

• {link_id} is the ID of the link you've created. For example: cb65f82c-dc93-4d3e-8270-9a27528397f5.
• {date1} is the date from when you want to start getting transactions, in YYY-MM-DD format. For example: 2024-02-01.
• {date2} is the date from when you want to finish getting transactions, in YYY-MM-DD format. For example: 2024-02-28.

In Postman, you should see a response similar to this one. For detailed information on the transaction fields returned, make sure to check out our Transactions API reference documentation.

Next steps

Now that you've tested out a simple flow, you should definitely:

• Read up on Links - they're essential for pretty much anything that you'll do with the Belvo API.
• Study our Sandbox article to see what other institutions you can connect with and get familiar with different login flows.