Pagination & Filtering

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

number

default:"20"

The maximum number of records provided in the current response.

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.

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

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "Link": {
      "type": "string",
      "pattern": "<([^>]+)>;\\s*rel=\"(self|prev|next|last|first)\""
    }
  }
}

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:

number

default:"20"

The maximum number of records provided in the current response.

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.

string

The current sort order and direction.See the Sort section below for more information.

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).

number

The total number of records available.

object

The filters applied to the request. This object contains key-value pairs where each key is a field name and each value is either a simple equality value or an object with operator-based filters.When filters are applied, the totalCount reflects the total number of records matching the filter criteria, not the total number of all records.

{
    "meta": {
        "limit": 3,
        "offset": 5,
        "sort": "displayName",
        "currentCount": 5,
        "totalCount": 103,
        "filters": {}
    },
    "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"
        }
    ]
}

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "data": {
      "type": "array",
      "items": {
        // This would be the data type of the list
      }
    },
    "meta": {
      "type": "object",
      "properties": {
        "limit": {
          "type": "integer",
          "minimum": 0
        },
        "offset": {
          "type": "integer",
          "minimum": 0
        },
        "sort": {
          "type": "string",
          "pattern": "^(-?\\w+)(,-?\\w+)*$"
        },
        "currentCount": {
          "type": "integer",
          "minimum": 0
        },
        "totalCount": {
          "type": "integer",
          "minimum": 0
        },
        "filters": {
          "type": "object",
          "additionalProperties": true
        }
      },
      "required": [
        "limit",
        "offset",
        "sort",
        "currentCount",
        "totalCount",
        "filters"
      ]
    }
  },
  "required": [
    "data",
    "meta"
  ]
}

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)

{
    "meta": {
        "limit": 3,
        "offset": 5,
        "sort": "displayName",
        "currentCount": 3,
        "totalCount": 103,
        "filters": {}
    },
    "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"
        }
    ]
}

Link: <https://api.payrollintegrationsapp.com/v1/foobar?limit=3&offset=5>; rel="self"; <https://api.payrollintegrationsapp.com/v1/foobar?limit=3&offset=0>; rel="prev", <https://api.payrollintegrationsapp.com/v1/foobar?limit=3&offset=10>; rel="next", <https://api.payrollintegrationsapp.com/v1/foobar?limit=3&offset=100>; rel="last", <https://api.payrollintegrationsapp.com/v1/foobar?limit=3&offset=0>; rel="first"

Descending Sort

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

{
    "meta": {
        "limit": 3,
        "offset": 0,
        "sort": "-displayName",
        "currentCount": 3,
        "totalCount": 103,
        "filters": {}
    },
    "data": [
        {
            "id": "34567a89-f6d8-4c47-b1db-c41d981a555e",
            "displayName": "Viridian City Waste Management"
        },
        {
            "id": "1226ecf9-136b-43bc-8943-4f7b39a32b0c",
            "displayName": "Vermilion City Power Company"
        },
        {
            "id": "b70b563c-6983-4d79-858d-07477ccb4bd1",
            "displayName": "Saffron City Hotel"
        }
    ]
}

Link: <https://api.payrollintegrationsapp.com/v1/foobar?limit=3&offset=0&sort=-displayName>; rel="self", <https://api.payrollintegrationsapp.com/v1/foobar?limit=3&offset=5&sort=-displayName>; rel="next", <https://api.payrollintegrationsapp.com/v1/foobar?limit=3&offset=100&sort=-displayName>; rel="last", <https://api.payrollintegrationsapp.com/v1/foobar?limit=3&offset=0&sort=-displayName>; rel="first"

Using `Link` Headers

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.

Filtering

Many endpoints in the Payroll Integrations API support filtering to retrieve a subset of records that match specific criteria. For example, /v1/payroll-connections/:payroll_connection/employee-data?updatedAt[gt]=2026-01-01 returns only employee data which has been updated after January 1st, 2026. This section outlines the filtering syntax, supported operators, and how to combine multiple filters.

Query Parameters

Filters are applied using query parameters with the following syntax:

string

Simple equality filter. Returns records where the field exactly matches the value.

string

Operator-based filter. Returns records where the field matches the value according to the specified operator.See the Operators section below for the full list of supported operators.

/v1/payroll-connections/:payroll_connection/employee-data?updatedAt=2024-01-01

/v1/payroll-connections/:payroll_connection/employee-data?updatedAt[gte]=2024-01-01

/v1/payroll-connections/:payroll_connection/employee-data?updatedAt[gte]=2024-01-01&updatedAt[lte]=2024-12-31

Operators

The following operators are supported for filtering. Not all operators are available for every field; the allowed operators depend on the field’s data type.

Operator	Description	Example
(none)	Equal (default)	`?status=active`
`eq`	Equal	`?status[eq]=active`
`ne`	Not equal	`?status[ne]=deleted`
`gt`	Greater than	`?amount[gt]=100`
`gte`	Greater than or equal	`?createdAt[gte]=2024-01-01`
`lt`	Less than	`?amount[lt]=500`
`lte`	Less than or equal	`?createdAt[lte]=2024-12-31`
`in`	Matches any value in list	`?status[in]=active,pending`
`not_in`	Does not match any value in list	`?status[not_in]=deleted,archived`
`contains`	Case-insensitive substring inclusion	`?displayName[contains]=middle`
`not_contains`	Case-insensitive substring exclusion	`?displayName[not_contains]=another`
`empty`	Field is null	`?deletedAt[empty]=true`
`not_empty`	Field is not null	`?email[not_empty]=true`

Combining Multiple Filters

Multiple filters can be applied in a single request by including multiple query parameters. All filters are combined using AND logic, meaning records must match all specified conditions.

/v1/payroll-connections/:payroll_connection/employee-data?updatedAt[gte]=2024-01-01&id[in]=10,20

Array Operators

The in and not_in operators accept comma-separated values:

/v1/payroll-connections/:payroll_connection/employee-data?id[in]=1,2,3

/v1/payroll-connections/:payroll_connection/employee-data?id[not_in]=4,5,6

Null Checking

Use the empty and not_empty operators to filter on null values. These operators accept true or false as values:

[empty]=true or [not_empty]=false — field is null
[empty]=false or [not_empty]=true — field is not null

/v1/payroll-connections/:payroll_connection/employee-data?updatedAt[empty]=true

/v1/payroll-connections/:payroll_connection/employee-data?updatedAt[not_empty]=true

/v1/payroll-connections/:payroll_connection/employee-data?updatedAt[empty]=false

Filter Error Handling

The API returns 400 Bad Request in the following cases:

Unknown filter field: Attempting to filter on a field that does not support filtering
Invalid operator: Using an operator that is not allowed for the specified field
Invalid value: Providing a value that does not match the expected field type (e.g., non-UUID value for a UUID field)

{
    "error": {
        "code": "BAD_REQUEST",
        "message": "Unknown filter field 'invalidField'"
    }
}

{
    "error": {
        "code": "BAD_REQUEST",
        "message": "Operator 'contains' is not allowed for field 'id'. Allowed operators: eq, ne, in, not_in"
    }
}

{
    "error": {
        "code": "BAD_REQUEST",
        "message": "Invalid value for field 'id': 'not-a-uuid'"
    }
}

Response Metadata

When filters are applied to a request, the response metadata includes a filters object that reflects the active filters:

/v1/payroll-connections/:payroll_connection/employee-data?updatedAt[gte]=2024-01-01&updatedAt[lte]=2024-12-31

{
    "meta": {
        "limit": 20,
        "offset": 0,
        "currentCount": 15,
        "totalCount": 15,
        "filters": {
            "updatedAt": {
                "gte": "2024-01-01",
                "lte": "2024-12-31"
            }
        }
    },
    "data": [
        ...
    ]
}

Combining Filtering with Pagination

Filters can be combined with pagination parameters. Filters are applied first, then pagination is applied to the filtered results:

/v1/payroll-connections/:payroll_connection/employee-data?updatedAt[gte]=2024-01-01&limit=10&offset=20

{
    "meta": {
        "limit": 10,
        "offset": 20,
        "currentCount": 10,
        "totalCount": 156,
        "filters": {
            "updatedAt": {
                "gte": "2024-01-01"
            }
        }
    },
    "data": [
        ...
    ]
}

In this example, the totalCount reflects the total number of records matching the filter criteria (156 records with updatedAt >= 2024-01-01), not the total number of all records.

API documentation

Authentication

Employee Data

Employee Updates

Employer Identifiers

Invites

Meta

Pay Categories

Payroll Connections

Payroll Platforms

Payroll Records

Users

Introduction

Request

Query Parameters

Response

Data

Metadata

Sort

Examples

Ascending Sort

Descending Sort

Using `Link` Headers

Filtering

Query Parameters

Operators

Combining Multiple Filters

Array Operators

Null Checking

Filter Error Handling

Response Metadata

​Introduction

​Request

​Query Parameters

​Response

​Data

​Metadata

​Sort

​Examples

​Ascending Sort

​Descending Sort

​Using Link Headers

​Filtering

​Query Parameters

​Operators

​Combining Multiple Filters

​Array Operators

​Null Checking

​Filter Error Handling

​Response Metadata

​Combining Filtering with Pagination

Introduction

Request

Query Parameters

Response

Data

Metadata

Sort

Examples

Ascending Sort

Descending Sort

Using `Link` Headers

Filtering

Query Parameters

Operators

Combining Multiple Filters

Array Operators

Null Checking

Filter Error Handling

Response Metadata

Combining Filtering with Pagination