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.

Accounts response in PostmanAccounts response in Postman

Accounts response in Postman

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.

Transactions response in PostmanTransactions response in Postman

Transactions response in Postman

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.

Balances response in PostmanBalances response in Postman

Balances response in Postman

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.
  • Try our Quickstart application to see how an end-to-end application can look like.

Updated 2 months ago


Extract your first financial data


API keys? Check! Postman? Check! All that's left is to get some data!πŸ‘©β€πŸ’»

Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.