Filtering responses

Use filters to reduce responses sizes and bandwidth, ensuring you get just the data you need.

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 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=fieldA,fieldB
  • You want excluded in your response.
    omit=fieldA,fieldB

📘

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://api.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://api.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 you URL query to narrow down the responses you receive. Belvo supports the following operators for your queries:

Operator

Use when you want

Example

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

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

in

To get results for any of the listed elements. Works with strings.

fieldA__in=monday,wednesday,friday

=

To get results that exactly match a value.

fieldA=OpenFinance

&

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 transactions where the amount is greater than 600:

https://api.belvo.com/api/transactions/?amount__gt=600

See the Examples section for more inspiration.

📘

SDKs also support the filter functionality

For example in our Python SDK to search transactions, see list and filtering.

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.

"account": {
                "id": "084bc04e-881d-40f8-98df-b89ac4c25bc4",
                "number": "82433205",
                "balance": {
                    "current": 2979.5, // Target nested field
                    "available": 2979.5
                },
            }

🚧

Filterable fields

Not all fields are filterable by default. If you find that you aren't able to filter a certain field and would like to, please reach out to Belvo Support at [email protected]

Examples

Transaction equal to a given ID

Add ?id={the-id-you-want} to the end of your base URL:

https://api.belvo.com/api/transactions/?id=insert-id-here

Transactions within a date range

Add ?collected_at__range={start-date},{end-date} to the end of your base URL:

https://api.belvo.com/api/transactions/?collected_at__range=2020-01-01,2020-01-02

Transactions within a range and greater than a value

Add ?collected_at__range={start-date},{end-date}&amount__gt={value} to the end of your base URL:

https://api.belvo.com/api/transactions/?collected_at__range=2020-01-01,2020-01-02&amount__gt=600

Transactions from an account with certain balance

Add ?account__balance__current__gt={value} to the end of your base URL. 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

Add ?id__in={id1},{id2},{id3} to the end of your base URL.

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

Updated 29 days ago


Filtering responses


Use filters to reduce responses sizes and bandwidth, ensuring you get just the data you need.

Suggested Edits are limited on API Reference Pages

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