API Filtering, Sorting and Pagination

Many API endpoints, such as search and reports endpoints, can return multiple records. These endpoints support request parameters that allow you to search, filter, sort, and paginate the results.

Request

Depending on the endpoint, the request body may support the following properties:

• q for keyword searching.

• fields for selecting the fields returned in the response.

• filter for applying structured filter conditions.

• sort for controlling the order of the results.

• pagination for limiting the number of records returned.

The properties supported by each endpoint are documented in the endpoint reference.

Search Query

The q property performs a keyword search across the searchable fields supported by the endpoint.

{
  "q": "Brown"
}

The fields searched by the q property vary between endpoints. Refer to the endpoint documentation for details.

Selecting Fields

Use the fields property to specify which fields should be included in the response.

Each field must be specified using the format <objectApiName>-<fieldApiName>.

{
  "fields": [
    "students-first_name",
    "students-last_name",
    "students-dob"
  ]
}

The objects and fields available depend on the endpoint. Refer to the endpoint documentation for the supported objects and fields.

Selecting only the fields required by your integration reduces response size and improves performance.

Filtering

Use the filter property to return only records that match specific criteria.

A filter consists of one or more conditions combined using a logical operator.

{
  "filter": {
    "type": "and",
    "conditions": [
      {
        "field": "students-first_name",
        "operator": "gt",
        "value": "1"
      }
    ]
  }
}

The type property determines how the conditions are evaluated.

Conditions

Each condition includes:

Operators

The operators available for a filter condition depend on the data type of the field being filtered. For example, comparison operators such as gt and lt are supported for numeric and date fields, while text operators such as contains and starts_with are supported for text fields.

Sorting

Use the sort property to specify the order in which records are returned.

The field must be specified using the format <objectApiName>-<fieldApiName>.

{
  "sort": {
    "field": "agents-agent_name",
    "direction": "asc"
  }
}

The direction property accepts the following values:

Only fields supported by the endpoint can be used for sorting.

Pagination Request

Use the pagination property to control the number of records returned and the page to retrieve.

{
  "pagination": {
    "page": 1,
    "page_size": 50
  }
}

If omitted, the endpoint uses its default pagination settings.

The response includes a has_more flag to indicate if there are more records available on subsequent pages (view the section Pagination Response for more details).

Complete Request Example

{    
    "q": "Brown",
    "fields": [
        "students-student_number",
        "students-first_name",
        "students-last_name",
        "students-dob"
    ],
    "sort": {
        "field": "students-dob",
        "direction": "asc"
    },
    "filter": {
        "type": "and",
        "conditions": [
            {
                "field": "students-dob",
                "operator": "gte",
                "value": "2000-06-17"
            }
        ]
    },
    "pagination": {
        "page_size": 100,
        "page": 1
    }
}

Response

Pagination Response

When a request includes the pagination property, the response includes a meta.pagination object containing information about the page that was returned.

{
    "data": [
       {
            "id": 10294,
            "students-student_number": "AP10294",
            "students-first_name": "Adam",
            "students-last_name": "Brown",
            "students-dob": "2000-09-08"
        }
    ],
    "meta": {
        "pagination": {
            "page_size": 100,
            "page": 1,
            "has_more": false
        }
    }
}

The API does not return the total number of matching records or the total number of pages. Instead, it includes a has_more flag to indicate whether additional records are available on subsequent pages.