Pagination of Response Data

In Dayforce Release 56, a paging mechanism was added so that some RESTful API endpoints can return data in batches as pages. This was introduced to support large responses provided by features like GET Reports and GET Employee Punches. This allows both server and client to process each request with less data stored in memory and less data transmitted over the network.

For these endpoints, the response is divided into pages. Each page contains a Paging record with the link to the next page. The consuming application must check this Paging element to determine if there is more data to retrieve. When there is more data, the Paging element contains a Next property with the URI that points to the next page of data. You should use the URI to retrieve the subsequent pages of data. The Next property in the Paging element for the last page of data will have an empty string value. This is the indication to the client that this is the last page of data.

The following is an example of the Paging element showing that there is another page of data to retrieve:

{
  "Data": {
    ... this content removed for brevity ...
  },
  "Paging": {
    "Next": "https://usconfigr56.dayforcehcm.com:443/Api/ddn/V1/Reports/Payroll_Earning_Hours_Detail?cursor=cqkkpzMM%252F2%252Fxkfm67LcyOdPhDj94GYLl2gLOeMPaIiVkx8K1r5iDc3BqGkXo9qKU"
  }
}

The following example shows the Paging element for the final page of data. The Next link is an empty string:

{
  "Data": {
    ... this content removed for brevity ...
  },
  "Paging": {
    "Next": ""
  }
}

Number of Records Per Page

Most APIs that paginate data return 1,000 records per page by default, but that isn’t a static number of all APIs. You can specify the number of records that you want to receive per page by specifying a pageSize query string parameter. Although setting the page size isn’t recommended, it might be helpful in some scenarios, such as for testing purposes. If the pageSize query parameter isn’t used (which is the recommended approach), then the server uses a default value.

The following is an example that sets the page size to 2,500:

https://www.dayforcehcm.com/api/{clientName}/v1/Reports/{reportXRefCode}?pageSize=2500

Next Page Link

The next page link is a complete URL that you can use to retrieve the next page of data without modifying it. The URL contains the original query string parameters, plus an additional cursor parameter and value. The server uses the cursor as a pointer within the original data so that it understands what is the next set of data to return.

If there are no additional pages of data, the Next property will have a value of an empty string.