Skip to main content

​
Introduction

When a response from the Payroll Integrations API would include many results, the data is paginated and a subset is returned. For example, /v1/connections/{connection}/employees by default only returns the first 20 employees even if there are more employees available. This page outlines how the response is structured for all paginated endpoints and how to configure the amount and order of the results.

​
Request

​
Query Parameters

​
limit
number
default:"20"
The maximum number of records provided in the current response.
​
offset
number
default:"0"
The starting point for retrieving records with respect to the beginning of the list.The resulting list is inclusive and zero-indexed with respect to the offset value.
​
sort
string
The current sort order and direction.sort is a single string value following the regular expression format of ^(-?\w+)(,-?\w+)*$.See the Sort section below for more information.
/v1/foobar?limit=3&offset=5&sort=displayName

​
Response

​
Data

All returned records are located in the data property in the response.

​
Metadata

Pagination metadata is provided in the meta property in the response. It contains the following properties:
​
limit
number
default:"20"
The maximum number of records provided in the current response.
​
offset
number
default:"0"
The starting point for retrieving records with respect to the beginning of the list.The resulting list is inclusive and zero-indexed with respect to the offset value.
​
sort
string
The current sort order and direction.See the Sort section below for more information.
​
currentCount
number
The number of records in the current response.Note: This is not the same as limit. For example, a request can be configured to return a maximum of 20 records (limit) and only return 3 records (currentCount).
​
totalCount
number
The total number of records available.
{
    "meta": {
        "limit": 3,
        "offset": 5,
        "sort": "displayName",
        "currentCount": 5,
        "totalCount": 103
    },
    "data": [
        {
            "id": "34567a89-f6d8-4c47-b1db-c41d981a555e",
            "displayName": "Azalea Town Landscaping"
        },
        {
            "id": "1226ecf9-136b-43bc-8943-4f7b39a32b0c",
            "displayName": "Blackthorn City Mining"
        },
        {
            "id": "b70b563c-6983-4d79-858d-07477ccb4bd1",
            "displayName": "Cherrygrove City Sailing"
        }
    ]
}

​
Sort

The default sort property and direction varies depending on the endpoint. If the provided value is not a valid sortable property for the records, the endpoint returns 400 Bad Request, detailing which fields can be used for sorting. Even if the provided value is a valid property of the record schema, it does not guarantee that sorting is supported for that property. If the first character of sort is - (e.g. -sortProperty), the list of records is returned in descending order. To sort by multiple properties, separate the values by commas. The descending order syntax is also allowed for individual properties (e.g. sort=sortProperty,-anotherProperty). Note: This returns a 400 Bad Request if the multi-sort configuration is not supported.

​
Examples

​
Ascending Sort

GET `/v1/foobar?limit=3&offset=5&sort=displayName` (with total count being 103)

​
Descending Sort

GET `/v1/foobar?limit=3&sort=-displayName` (with total count being 103)
Each response also includes a Link header that contains the previous, next, first, and last “page” URLs that will need to be iterated through. limit is preserved for all relevant links provided while offset is changed depending on the page. Listed below are the link headers generated for a request with query parameters limit=30&offset=60 and a total of 160 records: 
Link: <https://api.payrollintegrationsapp.com/v1/payroll-platforms?limit=30&offset=60>; rel="self",
<https://api.payrollintegrationsapp.com/v1/payroll-platforms?limit=30&offset=30>; rel="prev",
<https://api.payrollintegrationsapp.com/v1/payroll-platforms?limit=30&offset=90>; rel="next",
<https://api.payrollintegrationsapp.com/v1/payroll-platforms?limit=30&offset=150>; rel="last",
<https://api.payrollintegrationsapp.com/v1/payroll-platforms?limit=30&offset=0>; rel="first"
The Link header provides the URL for the previous, next, first, and last page of results:
  • The URL for the current page is followed by rel="self".
  • The URL for the previous page is followed by rel="prev".
  • The URL for the next page is followed by rel="next".
  • The URL for the last page is followed by rel="last".
  • The URL for the first page is followed by rel="first".
In some cases, only a subset of these links are available. For example, the link to the previous page is not be included on the first page of results, and the link to the next page is not be included on the last page of results.