Pagination

Learn how to properly consume endpoints that return multiple resources.

Nearly all endpoints provided by this API that return more than one resource at a time will paginate their response. A paginated endpoint will have a different response structure than one that returns a single resource.

Apart from the actual data, the paginated response structure will always be identical across all endpoints so you can safely rely on its structural integrity. Here is what the structure of a paginated response looks like:

Pagination structure

JSON

{
  "current_page": 1,
  "data": [{},{},{}],
  "first_page_url": "https:\/\/classic-api.contractorscloud.com\/api\/v1\/projects?page%5Bnumber%5D=1",
  "from": 1,
  "last_page": 118,
  "last_page_url": "https:\/\/classic-api.contractorscloud.com\/api\/v1\/projects?page%5Bnumber%5D=118",
  "links": [
    {
      "url": null,
      "label": "« Previous",
      "active": false
    },
    {
      "url": "https:\/\/classic-api.contractorscloud.com\/api\/v1\/projects?page%5Bnumber%5D=1",
      "label": "1",
      "active": true
    },
    {
      "url": "https:\/\/classic-api.contractorscloud.com\/api\/v1\/projects?page%5Bnumber%5D=2",
      "label": "2",
      "active": false
    },
    {
      "url": "https:\/\/classic-api.contractorscloud.com\/api\/v1\/projects?page%5Bnumber%5D=3",
      "label": "3",
      "active": false
    },
    {
      "url": "https:\/\/classic-api.contractorscloud.com\/api\/v1\/projects?page%5Bnumber%5D=4",
      "label": "4",
      "active": false
    },
    {
      "url": "https:\/\/classic-api.contractorscloud.com\/api\/v1\/projects?page%5Bnumber%5D=5",
      "label": "5",
      "active": false
    },
    {
      "url": "https:\/\/classic-api.contractorscloud.com\/api\/v1\/projects?page%5Bnumber%5D=6",
      "label": "6",
      "active": false
    },
    {
      "url": "https:\/\/classic-api.contractorscloud.com\/api\/v1\/projects?page%5Bnumber%5D=7",
      "label": "7",
      "active": false
    },
    {
      "url": "https:\/\/classic-api.contractorscloud.com\/api\/v1\/projects?page%5Bnumber%5D=8",
      "label": "8",
      "active": false
    },
    {
      "url": "https:\/\/classic-api.contractorscloud.com\/api\/v1\/projects?page%5Bnumber%5D=9",
      "label": "9",
      "active": false
    },
    {
      "url": "https:\/\/classic-api.contractorscloud.com\/api\/v1\/projects?page%5Bnumber%5D=10",
      "label": "10",
      "active": false
    },
    {
      "url": null,
      "label": "...",
      "active": false
    },
    {
      "url": "https:\/\/classic-api.contractorscloud.com\/api\/v1\/projects?page%5Bnumber%5D=117",
      "label": "117",
      "active": false
    },
    {
      "url": "https:\/\/classic-api.contractorscloud.com\/api\/v1\/projects?page%5Bnumber%5D=118",
      "label": "118",
      "active": false
    },
    {
      "url": "https:\/\/classic-api.contractorscloud.com\/api\/v1\/projects?page%5Bnumber%5D=2",
      "label": "Next »",
      "active": false
    }
  ],
  "next_page_url": "https:\/\/classic-api.contractorscloud.com\/api\/v1\/projects?page%5Bnumber%5D=2",
  "path": "https:\/\/classic-api.contractorscloud.com\/api\/v1\/projects",
  "per_page": 30,
  "prev_page_url": null,
  "to": 30,
  "total": 3531
}

The above example is from a paginated response of Projects but the structure and keys will always be the same for any paginated endpoint. The data key in the above example has been truncated but will be an array of resources / objects that you have requested. All other keys are there to assist you with pagination.

Performing pagination

You can perform pagination yourself by utilizing the page[size] and page[number] query parameters. The page[size] query parameter limits the amount of results returned to the specified value. The page[number] query parameter loads the results for the specified page. For example, if you wanted to load 5 projects at a time and return the 7th page of results, your request might look something like this:

GET : /api/v1/projects?page[size]=5&page[number]=7

To make pagination more convenient for you, the next_page_url and the previous_page_url values will already be fully marked up for you with all applicable query parameters. Additionally, the links array provides objects to help build complex pagination for tables.

---

✨ If your initial request includes query params such as sorts, filters or includes, those will already be present in any of the pagination links provided in the response.

---

Pagination defaults

By default, the Contractors Cloud API will return 30 results at a time with a maximum of 100 results at a time. With that being said, your value for the page[size] query parameter must be greater than or equal to 1 and less than or equal to 100.