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

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, 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. Copy and save the two values you need to query Belvo products: 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.

✳️ Done! Now let's download and set up our Postman collection so you can quickly test out how to interact with our API 😉.

Set up our Postman collection

With your API keys in hand, let's get you up and running with Postman 📬.

We've created a public Postman workspace so that you can quickly and easily start testing what data you can get using Belvo. In this article, you'll learn how to install and configure our collection.

📘

Make sure you've installed the Postman App for Windows, Mac, or Chrome and have logged into your Postman account.
If you encounter any SSL certificate issues, please make sure you have the latest version of Postman available (you can verify by clicking on help → check for updates).

Fork the Belvo API Collection

To use Belvo's API collection:

1. Go to Belvo's Postman workspace and click Watch. This way, if we ever make a change to the collection, you'll be automatically notified and you'll be able to pull the changes into your fork.
2. Click on Fork to fork the collection into your own private workspace.

✳️ Done! Let's quickly configure Postman so that you can easily use our API.

Configure Postman

Our Postman collections make use of environment variables to customize the requests that are sent. You can read more about environments in Postman's setting up an environment with variables article.

To create your environment variables:

1. In Postman, click the eye icon.
2. In the Environment section, click Add.

3. Name your Environment, for example: Belvo Sandbox.
4. Add the following environment variables:
   • secretId: your sandbox Secret Key ID.
   • secretPassword: your sandbox Secret Key PASSWORD.
   • baseUrl: https://sandbox.belvo.com .

🚧

Make sure that your secretId, secretPassword, and baseUrl are properly stored as the initial value AND current value. This is important to prevent potential errors.

5. Click Save.

✳️ Awesome! But before we go on, let's make sure that everything is working just fine with a simple call.

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 environment.
2. In the Belvo API folder, select Institutions → GET List.
3. Click Send.

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.
4. Retrieve the daily balances for an account over a couple of weeks.

👍

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

# check our python-client library on github
# https://github.com/belvo-finance/belvo-python
from belvo.client import Client

# Login to Belvo API
client = Client("Secret Key ID", "Secret Key PASSWORD", "https://sandbox.belvo.com")

# Register a link
link = client.Links.create(
    institution="{institution_name}",
    username="{bank_username}",
    password="{bank_password)"
)

# check our Ruby gem on github
# https://github.com/belvo-finance/belvo-ruby
require 'belvo'

sandbox = Belvo::Client.new(
  'Secret Key ID',
  'Secret Key PASSWORD',
  'https://sandbox.belvo.com'
)

sandbox.links.register(
  institution: '{institution_name}',
  username: '{bank_username}',
  password: '{bank_password)'
)

// check our node package on github
// https://github.com/belvo-finance/belvo-js

var belvo = require('belvo').default;

var client = new belvo(
  'Secret Key ID',
  'Secret Key PASSWORD',
  'https://sandbox.belvo.com'
);

client.connect()
  .then(function () {
    client.links.register('{institution_name}', '{bank_username}', '{bank_password)')
      .then(function (res) {
        console.log(res);
      })
      .catch(function (error) {
        console.log(error);
      });
});

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.
}

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

# check our python-client library on github
# https://github.com/belvo-finance/belvo-python
from belvo.client import Client

# Login to Belvo API
client = Client("Secret Key ID", "Secret Key PASSWORD", "https://sandbox.belvo.com")

# Retrieve accounts
accounts = client.Accounts.create(
  link="{link_id}"
)

# check our Ruby gem on github
# https://github.com/belvo-finance/belvo-ruby
require 'belvo'

sandbox = Belvo::Client.new(
  'Secret Key ID',
  'Secret Key PASSWORD',
  'https://sandbox.belvo.com'
)

sandbox.accounts.retrieve link: '{link_id}'

// check our node package on github
// https://github.com/belvo-finance/belvo-js

var belvo = require('belvo').default;

var client = new belvo(
  'Secret Key ID',
  'Secret Key PASSWORD',
  'https://sandbox.belvo.com'
);

client.connect()
  .then(function () {
    client.accounts.retrieve('{link_id}')
      .then(function (res) {
        console.log(res);
      })
      .catch(function (error) {
        console.log(error);
      });
});

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

# check our python-client library on github
# https://github.com/belvo-finance/belvo-python
from belvo.client import Client

# Login to Belvo API
client = Client("Secret Key ID", "Secret Key PASSWORD", "https://sandbox.belvo.com")

# Retrieve transactions
transactions = client.Transactions.create(
  "{link_id}",
  "{date1}",
  date_to="{date2}"
)

# check our Ruby gem on github
# https://github.com/belvo-finance/belvo-ruby
require 'belvo'

sandbox = Belvo::Client.new(
  'Secret Key ID',
  'Secret Key PASSWORD',
  'https://sandbox.belvo.com'
)

sandbox.transactions.retrieve(
  link: '{link_id}',
  date_from: '{date1}',
  options: {
    date_to: '{date2}'
  }
)

// check our node package on github
// https://github.com/belvo-finance/belvo-js

var belvo = require('belvo').default;

var client = new belvo(
  'Secret Key ID',
  'Secret Key PASSWORD',
  'https://sandbox.belvo.com'
);

client.connect()
  .then(function () {
    client.transactions.retrieve('{link_id}', '{date1}', { 'dateTo': '{date2}' })
      .then(function (res) {
        console.log(res);
      })
      .catch(function (error) {
        console.log(error);
      });
});

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: 2020-02-01.
• {date2} is the date from when you want to finish getting transactions, in YYY-MM-DD format. For example: 2020-02-03.

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.

Request some Balances

With the Belvo API, you can also request the daily account balances for a period of time - a great way to get an idea of your user's spendings and incomes.

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

curl -X POST \
  https://sandbox.belvo.com/api/balances/ \
  -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

# check our python-client library on github
# https://github.com/belvo-finance/belvo-python
from belvo.client import Client

# Login to Belvo API
client = Client("Secret Key ID", "Secret Key PASSWORD", "https://sandbox.belvo.com")

# Retrieve transactions
transactions = client.Balances.create(
  "{link_id}",
  "{date1}",
  date_to="{date2}"
)

# check our Ruby gem on github
# https://github.com/belvo-finance/belvo-ruby
require 'belvo'

sandbox = Belvo::Client.new(
  'Secret Key ID',
  'Secret Key PASSWORD',
  'https://sandbox.belvo.com'
)

sandbox.balances.retrieve(
  link: '{link_id}',
  date_from: '{date1}',
  options: {
    date_to: '{date2}'
  }
)

// check our node package on github
// https://github.com/belvo-finance/belvo-js

var belvo = require('belvo').default;

var client = new belvo(
  'Secret Key ID',
  'Secret Key PASSWORD',
  'https://sandbox.belvo.com'
);

client.connect()
  .then(function () {
    client.balances.retrieve('{link_id}', '{date1}', { 'dateTo': '{date2}' })
      .then(function (res) {
        console.log(res);
      })
      .catch(function (error) {
        console.log(error);
      });
});

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 balances, in YYY-MM-DD format. For example: 2020-02-01.
• {date2} is the date from when you want to finish getting balances, in YYY-MM-DD format. For example: 2020-02-15.

In Postman, you should see a response similar to this one. For detailed information on the balance fields returned, make sure to check out our Balances 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.