# Pagination

List endpoints use continuation token-based pagination to retrieve results across multiple requests.

## How It Works

1. For the first request, do not provide a `continuationToken`.
2. The response will include an `items` array and, if there are more results, a `continuationToken`.
3. Pass the returned `continuationToken` in the next request to retrieve the subsequent page of results.
4. Continue requesting with the latest `continuationToken` until the response returns `null` for `continuationToken`, indicating there are no more results.


## Parameters

| Parameter | Type | Required | Description |
|  --- | --- | --- | --- |
| `continuationToken` | `string` | No | The token from the previous response. Omit for the first page. |
| `pageSize` | `int` | No | The maximum number of items to return per page. Must be between 1 and 100. Defaults to 100. |


## Sorting

Some list endpoints support sorting via the `sortBy` parameter. The `sortBy` parameter is optional and accepts a list of sort options. Refer to each endpoint's documentation for the available sort fields.

## Filtering

List endpoints support filtering via the `filters` parameter. The available filter fields are endpoint-specific and some endpoints require that certain filters are set. Refer to each endpoint's documentation for the available filter criteria.

## Response Format

All list endpoints return a response in the following format:


```json
{
  "items": [
    ...
  ],
  "continuationToken": "eyJza2lwIjo..."
}
```

| Field | Type | Description |
|  --- | --- | --- |
| `items` | `array` | The list of items for the current page. |
| `continuationToken` | `string?` | A token to retrieve the next page, or `null` if this is the last page. |


## Example

The following example uses the **List Employees** endpoint to illustrate pagination.

### First Request

For the first page, send a `POST` request without a `continuationToken`:


```bash
curl -X POST https://api.bright.hr/employees/v1/query \
  -H "Authorization: Bearer YOUR_BEARER_TOKEN"
```

### First Response


```json
{
  "items": [ ... ],
  "continuationToken": "eyJza2lwIjo..."
}
```

The presence of a `continuationToken` indicates there are more results.

### Second Request

To retrieve the next page, send the `continuationToken` in the request body:


```bash
curl -X POST https://api.bright.hr/employees/v1/query \
  -H "Authorization: Bearer YOUR_BEARER_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"continuationToken": "eyJza2lwIjo..."}'
```

### Last Response

When there are no more results, `continuationToken` will be `null`:


```json
{
  "items": [ ... ],
  "continuationToken": null
}
```