Paging

Sometimes taking an API action, such as searching for customers, generates a collection of results. When that happens, we divide the results into "pages," with a certain number of results on each page, and send you just one of these pages. This feature is called paging.

How do I control paging?

There are two parameters you can use to control paging: page_size and page.

page_size

The page_size parameter controls how many items we'll return in a single response (how many items "per page").

For example, if you requested a list of products in the product catalog, you could specify a page_size of 20, and we would give you information about 20 products at a time.

page

The page parameter tells us which page of results you want to view.

For example, if you requested 20 products at a time again, but this time specified a page of 2, we'd give you information about products 21-40.

How do I know whether there are more pages?

When we respond to you with items from a collection, we'll tell you about the collection in our response: whether the collection has_more items than we've returned to you, and a record_count telling you how many items are on the page we sent you.

Examples of paged results

Here's an example of a response where more items exist in a collection than just the ones we've returned, so has_more is true. You would specify page_size 10 (the current record_count) and page 2 to view the next set of results.

{
  "ok": true,
  "has_more": true,
  "record_count": 10,
  "records": [
    {
      "note_id": 1000,
      "subject": "Payment #12345 created",
      "body": "A $500.00 payment was created with reference number #1234 and ID #1000",
      "created_date": "2017-08-03T14:15:11.747",
      "created_by": null,
      "customer_id": 1005,
      "order_id": null,
      "request_id": null,
      "task_id": null
    },
    {
      "note_id": 1001,
      ...
    },
    ...
  ]
}

Here's a response where there's just one page. This time, has_more is false.

{
  "ok": true,
  "has_more": false,
  "record_count": 3,
  "records": [
    {
      "task_type_id": 2,
      "description": "Customer Contact"
    },
    {
      "task_type_id": 3,
      "description": "Customer Order Confirmation"
    },
    {
      "task_type_id": 4,
      "description": "Outage"
    }
  ]
}