Filtering, Sorting, and Paging

List requests can be filtered using a filter query to restrict results returned in the response. Each API will also include a list of properties that support sorting, as well as paging object for navigating through large groups of returned resources.

Filtering, sorting, and paging querystring parameters can be combined.

Filtering

Most list requests will support some degree of filtering.

This filtering is handled through a dedicated query querystring parameter. This parameter takes in a special filter string, using a predefined set of keys unique to each API resource.

Filter strings are a collection of key:value pairs where the key represents the field to filter against, and the value represents how to limit results within that field. Each key:value pair is separate by a space (encoded as %20 in the URL).

Each filter string is treated as a collection of AND criteria.

Example

The GET /customers API supports the following filtering parameters:

An example of a filter string to only return active customers with a name that includes "John" would look like this:

https://api.spoonity.com/customers?query=n:john%20s:ACTIVE

Sorting

Some list requests will include a set of properties that support sorting.

This sorting is controlled using the sort and order querystring parameters.

The value provided by the sort parameter will indicate which property to sort by, and the order parameter will include which direction — either "ASC" or "DESC".

Example

An example of a valid set of sorting parameters would look like this:

https://api.spoonity.com/customers?sort=name&order=ASC

The order parameter is optional. In cases where it is not included, a default sorting direction will be used.

Paging

List requests will be denoted by having the individual elements of the response included within an items array.

Any request matching this criteria will also include a paging object which will include quick-navigation URLs for returning either the next or prev page of the result set, including any already-provided querystring parameters (like a filter or sorting direction).

next and prev will be null when reaching the end or start of the result set.

The limit and page querystring parameters are used to specify which range of results to return in the response.

If unspecified, the limit will default to 25, and the page will default to 1.

Example

https://api.spoonity.com/customers?limit=25&page=2

{
  "items": [
    {
      "id": "cust_175a9abec1882d12",
      "name": "John Smith",
      "email": "john.smith@example.com",
      "is_verified": true,
      "date_created": "2026-02-02T13:48:05.683Z",
      "date_updated": "2026-02-02T13:48:05.683Z",
      "status": "ACTIVE"
    }
    ...
  ],
  "next": "https://api.spoonity.com/customers?limit=25&page=3",
  "prev": "https://api.spoonity.com/customers?limit=25&page=1"
}