Pagination

How Company API v4 list endpoints paginate — and how the shape changed from earlier versions.

List endpoints are paginated. The response wraps its results in a data array alongside a metadata object describing the current page and the total result set.

The pagination shape changed in v4. If you're migrating an integration built against an earlier version, see Before v4 for the field mapping.

v4 pagination

{
  "data": [
    // ... up to `per_page` resources
  ],
  "metadata": {
    "page": 1,
    "per_page": 50,
    "total_pages": 7,
    "total_count": 340
  }
}

Metadata fields

Field	Description
`page`	The current page number.
`per_page`	Number of items returned per page.
`total_pages`	Total number of pages available.
`total_count`	Total number of items across all pages.

Query parameters

Parameter	Description
`page`	The page number to fetch. Defaults to `1`.
`per_page`	Number of results per page. The default is set per endpoint — `50` for most lists (including People), `100` for a few. There is no enforced maximum.
`offset`	Skip a number of results before the page starts.

curl "https://app.peopleforce.io/api/v4/people?page=2&per_page=100" \
  -H "X-API-KEY: <your_api_key>"

To walk the full result set, request page=1 and keep incrementing page until it reaches total_pages.

Response headers

The same pagination data is also returned as response headers, so you can paginate without parsing the body:

X-Total, X-Total-Pages, X-Per-Page, X-Page, X-Next-Page, X-Prev-Page, X-Offset.

Before v4

Earlier API versions (v1–v3) used a different metadata object and a fixed page size of 50:

{
  "data": [],
  "metadata": {
    "page": 1,
    "pages": 7,
    "count": 340,
    "items": 50
  }
}

When migrating to v4, update these field names:

Pre-v4	v4	Notes
`pages`	`total_pages`	Total number of pages.
`count`	`total_count`	Total number of items.
`items`	`per_page`	Pre-v4 was the count of items on the current page (50 except the last page); v4 `per_page` is the requested page size.
—	`page`	Unchanged — present in both.

v4 also adds a configurable per_page query parameter (pre-v4 was fixed at 50), the offset parameter, and the X-* pagination response headers.