Introduction
On this page you can find all the information you need regarding how pagination and filtering works with the Belvo API.
Pagination
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
.
Increase page_size
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'
Navigation properties
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.
}
Parameter | Description |
---|---|
count | The total number of results for your query. |
next | If available, the next page of results. If no page is available, this is set to null . |
previous | If available, the previous page of results. If no page is available, this is set to null . |
results | An array of results for your query. |
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
}
As you can see in the examples, any query parameters that you provide are then propagated to the next
value. For example, in the initial request we send through ?link=link_id&page_size=1000
, and in the response, we can see that these query parameters are persisted in the new URL in the next
parameter: ?link=link_id&page_size=1000&page=2
.
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
}
Filtering Responses
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.
Get only certain fields
You can use the fields
filter in your URL query to define which fields:
- You want returned in your response.
fields=field1,field2
- You want excluded in your response.
omit=field1,field2

You can only target first-level fields, which will return any nested fields

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).
GET https://sandbox.belvo.com/api/accounts/5a772f98-befc-4217-8ae7-a087e73a7c28/
HTTP/1.1 200 OK
Content-Type: application/json
Content-Size: 341 Bytes # Unfiltered size
{
"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"
}
GET https://sandbox.belvo.com/api/accounts/
5a772f98-befc-4217-8ae7-a087e73a7c28/?fields=id,balance # Filtered query
HTTP/1.1 200 OK
Content-Type: application/json
Content-Size: 73 Bytes # Returned filtered response
{
"id":"5a772f98-befc-4217-8ae7-a087e73a7c28",
"balance": {
"current": 63054.93,
"available": 62985.22
}
}
Filter response data
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 know which fields you can filter, check out our API reference docs. If you find that you aren't able to filter a certain field and would like to, please reach out to Belvo Support at support@belvo.com
Operator | Use when you want | Example |
---|---|---|
= | To get results that exactly match a value. | fieldA=OpenFinance |
gt | To get results that are greater than a given value. | fieldA__gt=5000 |
lt | To get results that are smaller than a given value. | fieldA__lt=6000 |
gte | To get results that are greater than or equal to a given value. | fieldA__gte=5000 |
lte | To get results that are smaller than or equal to a given value. | fieldA__lte=6000 |
in | To get results for any of the listed elements. Works with strings. | fieldA__in=monday,wednesday,friday |
range | To get results that are between two values. Works with dates and numbers. Separate the two values with a comma. | fieldA__range=1,5 |
& | To combine queries. | query1&query2 |

To use the operators, just add them to the end of the query field (remember to use double underscores, __
, between the field and the operator). The example below will only return accounts where the currency
is COP
and the balance_available
is between 3000
and 5000
:

Target nested fields
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
}
}

Below you'll see some examples of how to apply filters to your calls 🤓.
Transaction equal to a given ID
Use id={the-id-you-want}
:
https://api.belvo.com/api/transactions/?id=2259b916-41ec-4dcb-9a01-7865d9c0657e
Transactions from an account with certain balance
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://api.belvo.com/api/transactions/?account__balance__current__gt=1000
Account details for one of many account IDs
Use id__in={id1},{id2},{id3}
:
https://api.belvo.com/api/accounts/?id__in=
2259b916-41ec-4dcb-9a01-7865d9c0657e,
5a772f98-befc-4217-8ae7-a087e73a7c28,
574d4a4f-1101-4bb0-bb7c-e27a440af507
Links with a certain external_id
Use external_id={id}
:
https://api.belvo.com/api/links/?external_id={id}