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

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.

{
  "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.

curl "https://tuempresa.factura.com.do/api/v1/customers?pageNumber=2&pageSize=50&search=industrial" \
  -H "X-Api-Key: $FACTURA_API_KEY"

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();

Next steps