Pagination

All top-level API endpoints have support for bulk fetches via "list" API methods.

Handling Paginated Responses

Endpoints that can return a large number of items (like listing users or documents) are paginated. This means that instead of returning all results in a single, massive response, the data is returned in "pages."

You must be prepared to handle this paginated structure to retrieve all the results you need. All paginated endpoints in the Trust Swiftly API share the same consistent structure.

---

Understanding the Paginated Response

A paginated response contains three top-level objects: data, links, and meta.

Key	Description
data	An array containing the list of resource objects for the current page.
links	An object containing ready-to-use URLs for navigating through the pages.
meta	An object containing metadata about the paginated list, such as total counts.

The links Object

This object provides full URLs for easy navigation.

Link	Description
first	The URL for the first page of results.
last	The URL for the last page of results.
prev	The URL for the previous page. Will be null if you are on the first page.
next	The URL for the next page. Will be null if you are on the last page.

Best Practice: For the most robust integration, your application should use the full URLs provided in the links object for navigation rather than constructing your own. This protects your application from potential future changes to the URL structure.

The meta Object

This object provides detailed information about the current state of the pagination.

Field	Description
current_page	The page number you are currently viewing.
from	The item number of the first result on the current page.
last_page	The total number of pages available.
path	The base URL for the resource.
per_page	The number of items requested per page.
to	The item number of the last result on the current page.
total	The total number of items in the entire collection.

---

Controlling Pagination

You can control pagination using query parameters in your request URL.

Changing the Page Size (per_page)

To specify how many records you want per page, append the per_page parameter.

• Default: 15 items per page.

• Maximum: 100 items per page. If you request more than 100, the API will return 100.

Example: Requesting 50 users per page. GET /api/users?per_page=50

Requesting a Specific Page (page)

To navigate to a specific page, use the page parameter.

Example: Requesting the second page of 50 users. GET /api/users?per_page=50&page=2

---

Complete Example

Request

Here is a curl example requesting the first page of users, with a page size of 2.

curl --request GET \
  --url 'https://{sub-domain}.trustswiftly.com/api/users?per_page=2&page=1' \
  --header 'Authorization: Bearer YOUR_API_KEY' \
  --header 'Accept: application/json'

Response

{
    "data": [
        {
            "id": 1,
            "first_name": "John",
            "last_name": "Doe",
            // ... more user fields
        },
        {
            "id": 2,
            "first_name": "Jane",
            "last_name": "Smith",
            // ... more user fields
        }
    ],
    "links": {
        "first": "https://{sub-domain}.trustswiftly.com/api/users?page=1",
        "last": "https://{sub-domain}.trustswiftly.com/api/users?page=5",
        "prev": null,
        "next": "https://{sub-domain}.trustswiftly.com/api/users?page=2"
    },
    "meta": {
        "current_page": 1,
        "from": 1,
        "last_page": 5,
        "path": "https://{sub-domain}.trustswiftly.com/api/users",
        "per_page": 2,
        "to": 2,
        "total": 10
    }
}