Skip to main content

​
Pagination

Many endpoints in the Blinksale API return collections of resources, such as lists of clients, invoices, or estimates. To make these responses more manageable, the API uses pagination to split the results into smaller chunks.

​
How Pagination Works

For endpoints that support pagination, the following parameters can be used:
ParameterDescriptionDefault
per_pageNumber of items to return per page15
pagePage number to retrieve1

​
Requesting Paginated Data

To request paginated data, simply include the pagination parameters in your query string: 
GET /api/v1/clients?per_page=10&page=2
This request would retrieve the second page of clients, with 10 clients per page.

​
Pagination Response Structure

Paginated responses include metadata about the pagination state alongside the requested data. Here’s an example response structure: 
{
  "success": true,
  "message": "Clients retrieved successfully",
  "data": [
    // Array of resource objects
  ],
  "links": {
    "first": "https://app.blinksale.com/api/v1/clients?page=1",
    "last": "https://app.blinksale.com/api/v1/clients?page=5",
    "prev": null,
    "next": "https://app.blinksale.com/api/v1/clients?page=2"
  },
  "meta": {
    "current_page": 1,
    "from": 1,
    "last_page": 5,
    "path": "https://app.blinksale.com/api/v1/clients",
    "per_page": 15,
    "to": 15,
    "total": 67
  }
}

​
Pagination Metadata

The pagination metadata includes:
FieldDescription
current_pageThe current page number
fromThe index of the first item on the current page
last_pageThe total number of pages
pathThe base URL for the paginated resource
per_pageThe number of items per page
toThe index of the last item on the current page
totalThe total number of items across all pages
The response also includes helpful navigation links:
LinkDescription
firstURL to the first page
lastURL to the last page
prevURL to the previous page (null if on first page)
nextURL to the next page (null if on last page)

​
Handling Pagination in Your Application

When working with paginated resources, your application should:
  1. Make the initial request to the API endpoint
  2. Process the current page of results
  3. Check if there are more pages by looking at the next link
  4. If there are more pages and you need them, follow the next link to retrieve the next page
This approach allows you to efficiently navigate through large collections of data without overwhelming your application or the API server.