---
title: "Pagination and filters"
description: "List endpoint convention: pageNumber, pageSize and search; PagedResult response with items, totalCount and totalPages."
canonical: https://factura.com.do/en/desarrolladores/paginacion
lang: en
generator: factura.com.do docs-index
---

Conventions 

# Pagination and filters

Almost all list endpoints accept the same three query params and return the same `PagedResult<T>` shape. Learn it once and integrate across all paginated resources; the two exceptions (`units` and `payment-terms`) are described below.

## Summary

Pagination is **offset-based**: `pageNumber` and `pageSize`. The response includes `totalCount` and a precomputed `totalPages`. Additional filters (`isActive` on customers, suppliers and products) are documented on each resource page where applicable. `GET /api/v1/units` returns the full list without `PagedResult`; `GET /api/v1/payment-terms` extends the shape with `lastModification`.

## Query params

| Param      | Type   | Default | Description                                                            |
| ---------- | ------ | ------- | ---------------------------------------------------------------------- |
| search     | string | —       | Free-text search. Each resource defines the fields it matches against. |
| pageNumber | int    | 1       | 1-indexed.                                                             |
| pageSize   | int    | 10      | Page size. No published maximum.                                       |

## Response shape

The `PagedResult<T>` shape is the same for invoices, notes, purchases, expenses, contacts, products, taxes, withholdings and currencies. `totalCount` is the total count without the pagination filter and `totalPages` is pre-calculated by the API.

paged-result.json

```

{

  "items": [

    {

      "customerId": "5f0c3a8e-2b7d-4c1e-9a6f-3d8b2e1c7a40",

      "legalName": "Empresa Receptora SRL",

      "taxIdentification": "131000001"

    }

  ],

  "totalCount": 87,

  "pageNumber": 2,

  "pageSize": 50,

  "totalPages": 2

}


```

## Example

List the second page of customers with size 50, filtering by the word `industrial`.

GET /api/v1/customers

cURL TypeScript 

list-customers.sh

```

curl "https://tuempresa.factura.com.do/api/v1/customers?pageNumber=2&pageSize=50&search=industrial" \

  -H "X-Api-Key: $FACTURA_API_KEY"


```

list-customers.ts

```

const params = new URLSearchParams({

  pageNumber: "2",

  pageSize: "50",

  search: "industrial",

});


const res = await fetch(

  `https://tuempresa.factura.com.do/api/v1/customers?${params}`,

  { headers: { "X-Api-Key": process.env.FACTURA_API_KEY! } },

);

if (!res.ok) throw new Error(`factura.com.do: ${res.status}`);

const { items, totalCount, pageNumber, pageSize, totalPages } = await res.json();


```

If you exceed a reasonable size, split the work

We do not publish a formal maximum `pageSize`. For bulk synchronizations, split the load into blocks of 100 to 250 items and use the `totalCount` from the first response to calculate how many pages remain.

## Next steps

Next step 

## Continue here

- [  Catalog The resource with the most paginated list endpoints (products, taxes, currencies). ](/en/desarrolladores/catalogo)
- [  Contacts List customers and suppliers with search by name or RNC. ](/en/desarrolladores/contactos)
- [  Errors How the API reacts if pageSize or pageNumber are out of range. ](/en/desarrolladores/errores)