Pagination and filtering

Endpoints that return many records — customers, drivers, orders, invoices and so on — return them one page at a time. Most of them share the query parameters and response shape described on this page, and each also accepts its own filters.

Paging parameters

Parameter	Default	Description
page	1	The page to return, starting at 1. A value below 1 returns the first page.
itemsPerPage	20	How many items to return per page. Most endpoints accept up to 1000; some allow fewer. A larger value is reduced to the endpoint's maximum.

curl "https://api.rushhourapp.com/api/v1/Customers?page=2&itemsPerPage=50" \
  -H "Authorization: Bearer YOUR_TOKEN"

Paged responses

A paged list is returned inside data:

{
  "data": {
    "list": [
      { "customerId": 1042, "customerName": "Example Freight LLC" },
      { "customerId": 1043, "customerName": "Sample Logistics Inc" }
    ],
    "page": 2,
    "itemsPerPage": 50,
    "totalCount": 137
  },
  "messages": [],
  "errors": [],
  "otherMessages": [],
  "success": true
}

Field	Description
list	The items on this page.
page	The page you asked for.
itemsPerPage	The page size that was used — check it, because it shows when your value was reduced to the maximum.
totalCount	How many items match your filters across all pages.

The number of pages is totalCount divided by itemsPerPage, rounded up. Asking for a page past the end returns an empty list.

Reading every page

1. Request page=1 with the page size you want.
2. Process data.list.
3. If page × itemsPerPage is less than totalCount, request the next page and repeat.

Records can be added, changed or deleted while you page through a list, so an item can move between pages. If you need a complete copy, collect all pages and remove duplicates by the record's ID.

Some endpoints that return short lists are not paged: they return every item as an array directly in data. Check which shape an endpoint uses before you write code that pages through it.

Searching and sorting

Many list endpoints also accept these parameters:

Parameter	Description
searchTerm	Free-text search. Which fields it matches depends on the list — a customer search, for example, looks at names, contact details and addresses.
sortBy	The field to sort by. The fields you can sort by differ between endpoints, and not every list supports sorting.
sortDirection	Ascending or Descending.

Filters

Each list has its own filters, such as statuses, customers, drivers, zones or date ranges. A few rules apply to all of them:

• Several values — most filters take several values by repeating the parameter: ?customers=12&customers=15. Comma-separated values are not accepted unless an endpoint says otherwise — for example, the types parameter of global search is a comma-separated list.
• Enumerated values — pass the value's name, such as Active.
• True or false — pass true or false.
• Date ranges — many endpoints take a dateRange parameter twice: first the start, then the end, for example ?dateRange=2026-09-01T00:00:00.000Z&dateRange=2026-09-30T23:59:59.999Z. Always send both values. Some endpoints use separate start and end parameters instead. Whether the ends are included, and whether only the calendar date or the full time is compared, varies by endpoint — see Dates and time zones.
• Encoding — URL-encode parameter values, particularly search terms and timestamps with a + offset.

Permissions shape the results

Lists only contain records the signed-in user is allowed to see, and totalCount counts only those records. Two users can get different results from the same request — for example, when one of them may only view the customers they created. If a list is unexpectedly short, check the roles and permissions of the user or token you are using.