Pagination

Learn how to paginate through large result sets.

Overview

List endpoints that return multiple items support pagination using query parameters. This helps you efficiently work with large datasets by breaking them into smaller pages.

Query Parameters

Pagination Parameters

per_pageinteger

Number of results to return per page. Accepts values from 1 to 100. Defaults to 10.

pageinteger

Page number to retrieve (minimum 1). Defaults to 1.

sort_bystring

Field to sort results by. Supported fields vary by endpoint:

Customers & Vendors: "created_at", "name", "updated_at"
Donation Intents: "created_at" only

Defaults to "created_at".

sort_orderstring

Sort direction: "asc" for ascending or "desc" for descending. Defaults to "desc".

Response Format

Paginated responses include metadata to help you navigate through pages:

Example Paginated Response

{
  "data": [
    // ... array of results
  ],
  "current_page": 1,
  "from": 1,
  "to": 10,
  "per_page": 10,
  "last_page": 10,
  "total": 100
}

current_page: The current page number

from: Index of the first item on this page

to: Index of the last item on this page

per_page: Number of items per page

last_page: Total number of pages

total: Total number of items across all pages

Examples

Fetching the First Page

GET https://testing.impactapi.co/donation_intents?per_page=20&page=1

Fetching Subsequent Pages

GET https://testing.impactapi.co/donation_intents?per_page=20&page=2

With Sorting

GET https://testing.impactapi.co/donation_intents?per_page=20&page=1&sort_by=created_at&sort_order=asc

Best Practices

Use reasonable page sizes (10-50 items) for better performance
Check last_page to determine if more pages are available
Cache results when appropriate to reduce API calls
Consider the total count when displaying pagination UI
Use from and to to show users their position in the results

Implementation Example

Iterating Through All Pages

async function getAllDonationIntents() {
  const allIntents = [];
  let page = 1;
  let hasMore = true;

  while (hasMore) {
    const response = await fetch(
      `https://testing.impactapi.co/donation_intents?per_page=50&page=${page}`,
      {
        headers: {
          'Authorization': `Bearer ${process.env.IMPACT_API_KEY}`
        }
      }
    );

    const result = await response.json();
    allIntents.push(...result.data);

    hasMore = page < result.last_page;
    page++;
  }

  return allIntents;
}

Best Practices

Handling Out of Range Pages

When requesting a page number beyond last_page, the API returns a 200 status with an empty data array. The pagination metadata will still be included with accurate values.

// Requesting page 999 when only 10 pages exist
{
  "data": [],
  "current_page": 999,
  "from": null,
  "to": null,
  "per_page": 10,
  "last_page": 10,
  "total": 100
}

Always check last_page before making requests to avoid unnecessary API calls.

Query Parameters

Pagination Parameters

per_pageinteger

Number of results to return per page. Accepts values from 1 to 100. Defaults to 10.

pageinteger

Page number to retrieve (minimum 1). Defaults to 1.

sort_bystring

Field to sort results by. Supported fields vary by endpoint:

Customers & Vendors: "created_at", "name", "updated_at"
Donation Intents: "created_at" only

Defaults to "created_at".

sort_orderstring

Sort direction: "asc" for ascending or "desc" for descending. Defaults to "desc".

Response Format

Paginated responses include metadata to help you navigate through pages:

Example Paginated Response

{
  "data": [
    // ... array of results
  ],
  "current_page": 1,
  "from": 1,
  "to": 10,
  "per_page": 10,
  "last_page": 10,
  "total": 100
}

current_page: The current page number

from: Index of the first item on this page

to: Index of the last item on this page

per_page: Number of items per page

last_page: Total number of pages

total: Total number of items across all pages

Implementation Example

Iterating Through All Pages

async function getAllDonationIntents() {
  const allIntents = [];
  let page = 1;
  let hasMore = true;

  while (hasMore) {
    const response = await fetch(
      `https://testing.impactapi.co/donation_intents?per_page=50&page=${page}`,
      {
        headers: {
          'Authorization': `Bearer ${process.env.IMPACT_API_KEY}`
        }
      }
    );

    const result = await response.json();
    allIntents.push(...result.data);

    hasMore = page < result.last_page;
    page++;
  }

  return allIntents;
}

Best Practices

Handling Out of Range Pages

When requesting a page number beyond last_page, the API returns a 200 status with an empty data array. The pagination metadata will still be included with accurate values.

// Requesting page 999 when only 10 pages exist
{
  "data": [],
  "current_page": 999,
  "from": null,
  "to": null,
  "per_page": 10,
  "last_page": 10,
  "total": 100
}

Always check last_page before making requests to avoid unnecessary API calls.