Wristband APIs implement pagination to divide large datasets into smaller, manageable subsets. Two pagination methods are supported: offset pagination and cursor pagination. The following sections provide a detailed description of each.

Offset Pagination

Offset pagination supports traversing through ordered data sets by allowing you to specify an offset (the number of items to skip) and a size (the number of items to return per page).

Setting the Offset

Use the start_index query parameter to set the offset. It is 1-based, meaning counting starts at 1. For example, start_index=1 returns the first item, while start_index=2 skips the first item and starts from the second.

Setting the Page Size

Use the count query parameter to specify the number of items that should be returned per page. For example, count=10 means each page will contain at most 10 items.

Sorting Results

The sort_by query parameter specifies the order of the paginated results. Its value must follow the syntax below:

<sort_attribute>[:(asc|desc)],...

For example, if we wanted to call the Query Tenant Users API, and sort the results by the user's family name in descending order, we would set the sort_by query parameter to the following:

sort_by=familyName:desc

The attributes that can be used in the sort_by query parameter depend on the API. Refer to the Sort Attributes section in the API documentation for the list of supported attributes.

A few additional things to note about sorting results:

If multiple sort attributes are specified, attributes listed earlier have higher priority. For example, sort_by=familyName:asc,givenName:desc sorts by familyName first, then by givenName.
If the sort order (asc or desc) is not specified, it defaults to asc. For example, sort_by=familyName is equivalent to sort_by=familyName:asc

Offset Pagination Response Body

Below is a table listing the fields that will be included in an offset pagination response.

Name	Type	Description
totalResults	Integer	The total number of items that exist across all pages.
startIndex	Integer	1-based index of the first result in the current page.
itemsPerPage	Integer	The total number of items per page.
items	`List<Item>`	List of items. The first item in the list will be the item at the offset specified by the `startIndex`. The size of the list will be no bigger than `itemsPerPage`.

Example Request

To help illustrate how offset pagination works, let's look at an example request to the Query Application Users API:

ℹ️
Note
When using the fields query parameter, you don’t need to include items in path expressions. Fields are matched directly against the entities in the items list

GET https://yourapp-yourorg.us.wristband.dev/api/v1/applications/app123/users?start_index=1&count=2&sort_by=givenName:asc&fields=id,givenName

In this case, the response might look like the following:

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8

{
  "totalResults": 4,
  "startIndex": 1,
  "itemsPerPage": 2,
  "items": [
    {
      "id": "x25rpgafgvgedcvjw52ooul3xm",
      "givenName": "Alice"
    },
    {
      "id": "4a47jcm2ejayovsgbgbpkihblu",
      "givenName": "Bill"
    }
  ]
}

In the response, totalResults is 4, indicating there are four users in application app123. However, because count is set to 2, only the first two users appear in the items list. To retrieve the remaining two users, repeat the request with start_index=3:

GET https://yourapp-yourorg.us.wristband.dev/api/v1/applications/app123/users?start_index=3&count=2&sort_by=givenName:asc&fields=id,givenName

Now the returned results would contain the remaining two users:

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8

{
  "totalResults": 4,
  "startIndex": 3,
  "itemsPerPage": 2,
  "items": [
    {
      "id": "47jcm2ejayovsgbgbpkihblu4a",
      "givenName": "Chris"
    },
    {
      "id": "hblu4a47jcm2ejayovsgbgbpki",
      "givenName": "Dan"
    }
  ]
}

Cursor Pagination

Cursor pagination supports traversing through ordered data sets by providing a cursor (pointer) to a specific item in the data set. The cursor can then be used to navigate to the next or previous page.

Navigating Pages Using Cursors

For APIs that support cursor pagination, the response body may include two cursor values, depending on whether previous or next pages exist:

pageBeforeCursor - A cursor for navigating to the previous page. Present only if a previous page exists.
pageAfterCursor - A cursor for navigating to the next page. Present only if a next page exists.

Navigating to the Next Page

To retrieve the next page, use the pageAfterCursor value from the response as the page_after query parameter in your request. For example, if you were calling the Fetch Tenants API and got a response like the following:

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8

{
  "pageAfterCursor": "dGVzdDIsczJuNHhtYmFyYmJwZmxpYWFvYm9pdWV5djQ",
  "items": [
    {
      "tenantId": "pl4a4aa4jzydksmrf3jnu5yfcw",
			...
    }
  ]
}

To go to the next page, you would take the value from the pageAfterCursor and construct a request like the following:

GET https://yourapp-yourorg.us.wristband.dev/api/v1/tenant-discovery/fetch-tenants?count=10&page_after=dGVzdDIsczJuNHhtYmFyYmJwZmxpYWFvYm9pdWV5djQ

You can repeat this process until pageAfterCursor is undefined, indicating that you've reached the last page.

Navigating to the Previous Page

To retrieve the previous page, use the pageBeforeCursor value from the response as the page_before query parameter in your request. For example, if you were calling the Fetch Tenants API and got a response like the following:

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8

{
  "pageBeforeCursor": "dGVzdDIsczJuNHhtYmFyYmJwZmxpYWFvYm9pdWV5djQ",
  "items": [
    {
      "tenantId": "pl4a4aa4jzydksmrf3jnu5yfcw",
			...
    }
  ]
}

To go to the previous page, you would take the value from the pageBeforeCursor and construct a request like the following:

GET https://yourapp-yourorg.us.wristband.dev/api/v1/tenant-discovery/fetch-tenants?count=10&page_before=dGVzdDIsczJuNHhtYmFyYmJwZmxpYWFvYm9pdWV5djQ

You can repeat this process until pageBeforeCursor is undefined, indicating that you've reached the first page.

Setting the Page Size

Use the count query parameter to specify the number of items that should be returned per page. For example, count=10 means each page will contain at most 10 items.