# Introduction

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

Article Does Not Apply to Direct Debit Mexico
This article does not apply to our Direct Debit (Payments) in Mexico product.

## 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:

```shell Increase Page Size Example
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:

```json Navigation Properties
{
  "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`:

```shell Example List Request
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:

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

Propagated query parameters
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:

```json Initial 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
}
```

```json Second response
{
  "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
}
```

```json Third response
{
  "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
}
```

```json Final response
{
  "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` 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).

| Parameter | Use | Example |
|  --- | --- | --- |
| `fields` | When you want only include these fields in your response | `https://sandbox.belvo.com/api/{endpoint}/?fields=field1,field2` |
| `omit` | When you don't want the given fields included in your response | `https://sandbox.belvo.com/api/{endpoint}/?omit=field3,field4` |


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

Unfiltered
When not using `filter`, the content size of this response is `341 Bytes`.

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

```json Unfiltered Response
{
  "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"
}
```

Filtered
Using `filter` to just retrieve the `id` and `balance`, the content size of the response payloads shrinks to `73 Bytes`

```shell Filtered Request
curl --request GET \
     --url 'https://sandbox.belvo.com/api/accounts/5a772f98-befc-4217-8ae7-a087e73a7c28/?fields=id,balance' \
     --header 'accept: application/json'
```

```json Filtered Response
{
  "id":"5a772f98-befc-4217-8ae7-a087e73a7c28",
  "balance": {
      "current": 63054.93,
      "available": 62985.22
  }
}
```

### Filter response data with operators

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

Filterable Fields per Endpoint
To know which fields you can filter by in the query string (including nested fields), check out the **Query** section of the LIST method for any resource in our API reference docs. For example, here are the query parameters for our  Accounts resource.

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 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`:

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

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

```json Targeting Nested Fields JSON Example
{
  "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 (`__`).

```shell Targeting Nested Fields Request Example
curl --request GET \
     --url 'https://sandbox.belvo.com/api/accounts/?account__balance__current__range=3000,5000' \
     --header 'accept: application/json'
```

Filterable Fields per Endpoint
To know which fields you can filter by in the query string (including nested fields), check out the **Query** section of the LIST method for any resource in our API reference docs. For example, here are the query parameters for our  Accounts resource.

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

### Examples

### Transaction equal to a given ID

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

```shell Transaction Equal to a Given ID Example
https://sandbox.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`:

```shell Transaction from an Account with a Certain Balance Example
https://sandbox.belvo.com/api/transactions/?account__balance__current__gt=1000
```

#### Account details for one of many account IDs

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

```shell Account Details for many Account IDs Example
https://sandbox.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}`:

```shell External ID Example
https://sandbox.belvo.com/api/links/?external_id={id}
```