Pagination

When calling the People Cloud API, some endpoints may return a large number of records.
This guide covers pagination for both the inquiries listing and the positions (order needs) endpoints. Use query parameters to page through results and reduce payload sizes.

---

Query Parameters

Parameter	Type	Description
page	integer	The page number to retrieve (default: 1)
per_page	integer	Number of items per page (e.g., 5, 10, 50)

How Pagination Works

Paginated responses include metadata such as:

• current_page
• per_page
• total
• last_page
• links (e.g., next, prev, first, last)

---

Example Request

To request a specific page of results, use the page query parameter:

Positions

cURL

curl -s -X GET \
  "http://127.0.0.1:8000/api/public/inquiry/1/positions?page=1&per_page=5" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Accept: application/json" | jq

Inquiries

cURL

curl -s -X GET \
  "http://127.0.0.1:8000/api/public/inquiries?page=1&per_page=10&q=cloud" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Accept: application/json" | jq

---

Paginated Response (Sample)

Example response structure for positions

JSON

{
  "current_page": 1,
  "data": [ /* array of position objects up to `per_page` */ ],
  "first_page_url": "...",
  "from": 1,
  "last_page": 2,
  "last_page_url": "...",
  "next_page_url": "...",
  "path": "...",
  "per_page": 5,
  "prev_page_url": null,
  "to": 5,
  "total": 9
}

---

Example response structure for inquiries

JSON

{
  "total": 7,
  "per_page": 10,
  "current_page": 1,
  "last_page": 1,
  "from": 1,
  "to": 7,
  "orders": [ /* array of inquiry summary objects */ ]
}

---

Pagination Fields Explained

Field	Description
current_page	The current page number
data	Array of returned records (up to per_page count)
total	Total number of records in the dataset
per_page	Number of items per page as requested
last_page	Total number of pages available
from, to	Range of items shown on the current page
next_page_url	Full URL to fetch the next page
prev_page_url	Full URL to fetch the previous page
first_page_url	Full URL to fetch the first page
last_page_url	Full URL to fetch the last page

Tips

• If per_page=1, the last_page equals total items (e.g. 9 items = 9 pages).
• If per_page=5, and total items = 9, then last_page = 2.

• Use .last_page in frontend to build pagination buttons.

• When piping curl into jq, avoid -i which prints response headers. Use -s (silent) so only the JSON body reaches jq:

curl -s "http://127.0.0.1:8000/api/public/inquiries?page=1&per_page=10" \
  -H "Authorization: Bearer $TOKEN" -H "Accept: application/json" | jq

• Note about inquiries: the controller applies some filtering in-memory and then returns pagination metadata based on the filtered collection. This is correct for the filtered results but may be less efficient than DB-side pagination for very large datasets.

Example: Show All Pages

To Get total number of pages (if per_page=1)

cURL

curl -s -X GET "http://127.0.0.1:8000/api/public/inquiry/1/positions?page=1&per_page=1" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Accept: application/json" | jq '.last_page'

Then loop through pages to retrieve all records.

---

Notes

• Pagination is server-side. You must request each page individually.