Introduction

On this page you can find all the information you need regarding how pagination and filtering works with the Belvo API.

We strongly recommend that you use the link query parameter in your List requests so that you only receive results for a given link.id.

When using the List method, by default you will receive 100 results per page. However, you can increase this to a maximum of 1000 results using the page_size query parameter:

curl --request GET \
--url 'https://sandbox.belvo.com/api/transactions/?link=link_id&page_size=1000'

In the response for any List request, you will receive navigation properties in the root of the response to aid you in your subsequent requests:

{
  "count": 3542,
  "next": "https://sandbox.belvo.com/api/transactions/?link=link_id&page_size=1000&page=2",
  "previous": null,
  "results": [] // Up to 1000 results, depending on page_size parameter.
}

In the case that there are more results than the upper limit set by page_size, You will need to use the value of the next parameter to receive the next page of results (which uses the page query parameter).

For example, in the case that you make the following List call, setting page_size to 1000:

curl --request GET \
     --url 'https://sandbox.belvo.com/api/transactions/?link=link_id&page_size=1000' \
     --header 'accept: application/json'

You will receive the following JSON response:

{
  "count": 3542,
  "next": "https://sandbox.belvo.com/api/transactions/?link=link_id&page_size=1000&page=2",
  "previous": null,
  "results": [] // Up to 1000 results
}

You can then use the URL in the next parameter to make your following API calls until next is equal to null. In the code block below we provide you an example of all the responses given this situation:

{
  "count": 3542,
  "next": "https://sandbox.belvo.com/api/transactions/?link=link_id&page_size=1000&page=2",
  "previous": null,
  "results": [] // Up to 1000 results
}

{
  "count": 3542,
  "next": "https://sandbox.belvo.com/api/transactions/?link=link_id&page_size=1000&page=3",
  "previous": "https://sandbox.belvo.com/api/transactions/?link=link_id&page_size=1000&page=1",
  "results": [] // Up to 1000 results
}

{
  "count": 3542,
  "next": "https://sandbox.belvo.com/api/transactions/?link=link_id&page_size=1000&page=4",
  "previous": "https://sandbox.belvo.com/api/transactions/?link=link_id&page_size=1000&page=2",
  "results": [] // Up to 1000 results
}

{
  "count": 3542,
  "next": null,
  "previous": "https://sandbox.belvo.com/api/transactions/?link=link_id&page_size=1000&page=3",
  "results": [] // Up to 1000 results
}

Using filters in your request can significantly cut down on the response size from the server as well as ensure that you eliminate any of the data that you don't need to get the job done.

You can use the fields and omit filters in your URL query to define which fields you want to receive in the JSON response from the Belvo API. We recommend that you use these fields exclusively, as in, do not combine fields and omit in the same query. Additionally, you can only use the fields and omit filters on root-level fields (and no on nested field).

This is particularly useful if you want to minimize the content size of API responses. For example, when querying the accounts endpoint, instead of receiving the entire response from the server, you can add ?fields=id,balance to the end of your query to get just the account ID and the balance (see the Filtered tab in the code example below).

curl --request GET \
     --url 'https://sandbox.belvo.com/api/accounts/5a772f98-befc-4217-8ae7-a087e73a7c28/' \
     --header 'accept: application/json'

{
  "id":"5a772f98-befc-4217-8ae7-a087e73a7c28",
  "type":"Créditos",
  "name":"CRED PREST BANAMEX",
  "number":null,
  "category":"LN",
  "collected_at":"2019-08-13T08:00:44.251929Z",
  "bank_product_id":"18",
  "currency":"MXN",
  "balance": {
      "current": 63054.93,
      "available": 62985.22
  },
  "link":"2259b916-41ec-4dcb-9a01-7865d9c0657e",
  "internal_identification":"1"
}

You can use additional filters in your URL query to narrow down the responses you receive. Belvo supports the following operators for your queries:

To use the operators, just add them to the end of your request URL as query fields. Remember to use double underscores, __, between the field and the operator and the ampersand , &, to chain query fields together. The example below will only return accounts where the currency is BRL and the balance_available is between 3000 and 5000:

curl --request GET \
     --url 'https://sandbox.belvo.com/api/accounts/?currency=BRL&balance_available__range=3000,5000' \
     --header 'accept: application/json'

You might want to target nested fields within the response. In the example below, if you wanted to target the current field, then the query path would be: account__balance__current. Please note that double underscores (__) are used to indicate that a field is nested within another field.

{
  "accounts": {
    "link": "57f212dc-1ba4-407f-b7f0-15a5e5ff17ae",
    "category": "CHECKING_ACCOUNT",
    "type": "Cuentas de efectivo",
    "number": "002180700688677950",
    "balance": {
      "available": 4523.48,
      "current": 4523.48
    }
  }
}

In the example request below, we are combining targeting a nested field (account__balance__current) as well with the range operator. Notice that both for the nested field and the operator, we add double underscores (__).

curl --request GET \
     --url 'https://sandbox.belvo.com/api/accounts/?account__balance__current__range=3000,5000' \
     --header 'accept: application/json'

Use id={the-id-you-want}:

https://sandbox.belvo.com/api/transactions/?id=2259b916-41ec-4dcb-9a01-7865d9c0657e

Use account__balance__current__gt={value} . You'll need to use double underscores to get the current balance as the current field is nested with balance and account:

https://sandbox.belvo.com/api/transactions/?account__balance__current__gt=1000

Use id__in={id1},{id2},{id3}:

https://sandbox.belvo.com/api/accounts/?id__in=
2259b916-41ec-4dcb-9a01-7865d9c0657e,
5a772f98-befc-4217-8ae7-a087e73a7c28,
574d4a4f-1101-4bb0-bb7c-e27a440af507

Use external_id={id}:

https://sandbox.belvo.com/api/links/?external_id={id}