> ## Documentation Index
> Fetch the complete documentation index at: https://docs.onboardme.app/llms.txt
> Use this file to discover all available pages before exploring further.

# Pagination and Incremental Sync

> OnboardMe list endpoints support pageNumber pagination and lastUpdated filtering. Learn how to page through results and set up incremental sync.

All OnboardMe list endpoints support pagination and incremental synchronization. Understanding these patterns is essential for building an efficient integration that stays in sync without unnecessary load.

## Pagination

List endpoints accept two optional query parameters:

| Parameter    | Type    | Default | Maximum | Description                     |
| ------------ | ------- | ------- | ------- | ------------------------------- |
| `pageNumber` | integer | 1       | 10000   | 1-based page index              |
| `pageSize`   | integer | 50      | 100     | Rows per page (where supported) |

Pages are 1-based: the first page is `pageNumber=1`, the second is `pageNumber=2`, and so on.

```http theme={null}
GET /api/v1/entities/list?pageNumber=2
```

<Note>
  Not all endpoints support `pageSize`. The entities and users list endpoints use a fixed server page size. The eForm templates endpoint supports both `pageNumber` and `pageSize`.
</Note>

### Paging through all records

To retrieve all records from an endpoint, iterate from `pageNumber=1` until you receive fewer records than the page size, or until the response's `hasMore` field (where present) is `false`.

```python theme={null}
page = 1
all_entities = []

while True:
    response = get("/api/v1/entities/list", params={"pageNumber": page})
    entities = response.json()
    all_entities.extend(entities)
    if len(entities) < PAGE_SIZE:
        break
    page += 1
```

## Incremental sync with lastUpdated

All major list endpoints accept a `lastUpdated` query parameter — a UTC ISO 8601 datetime. When provided, the endpoint returns only records that were created or modified **at or after** that timestamp.

```http theme={null}
GET /api/v1/entities/list?lastUpdated=2025-04-10T00:00:00Z
```

### Recommended sync pattern

1. On first run, do a **full import**: page through the list endpoint without `lastUpdated` until you have all records.
2. Store the timestamp of your last successful sync.
3. On subsequent runs, pass the stored timestamp as `lastUpdated` to fetch only changed records.
4. After a successful sync, update your stored timestamp.

```bash theme={null}
# Full import (first run)
curl "https://anzapi.onboardme.app/api/v1/entities/list?pageNumber=1" \
  -H "X-OM-Auth-ID: YOUR_CLIENT_ID" \
  -H "X-OM-Auth-Key: YOUR_CLIENT_SECRET"

# Incremental sync
curl "https://anzapi.onboardme.app/api/v1/entities/list?lastUpdated=2025-04-10T00:00:00Z" \
  -H "X-OM-Auth-ID: YOUR_CLIENT_ID" \
  -H "X-OM-Auth-Key: YOUR_CLIENT_SECRET"
```

<Warning>
  The `lastUpdated` value must not be in the future. Passing a future timestamp will result in a **400 Bad Request** error.
</Warning>

## Rate limits and polling frequency

The API enforces rate limits. When exceeded, you receive a **429 Too Many Requests** response with a `Retry-After` header indicating how many seconds to wait before retrying.

* Do not poll at a fixed high frequency
* Use `lastUpdated` to minimise the volume of data transferred
* Honour `Retry-After` and implement exponential backoff for resilience

```json theme={null}
{
  "status": 429,
  "title": "Too Many Requests"
}
```