Paging, Ordering, Sorting, and Filtering

Pagination

Endpoints that return collections of resources must limit the number of records returned in a given response. The query parameter limit can be used to alter the number of records returned. A typical endpoint will return 20 records by default and will allow a maximum of 100 records to be returned. The query parameter offset can be used to offset the result set. These query parameters can be combined to recover all records in a collection through a series of requests by incrementing the offset by the value of limit with each request.

  • limit: The number of results to display in each page (default = 20; max = 100).
  • offset: The starting point for the result set of a page. This is a zero-based index. For example, if there are 39 total records and the limit is the default of 20, use offset=20 to get the second page of results.

The total number of results in a collection can be found in the meta.total property of the response.

Ordering

The orders parameter is available to apply multiple sorting criteria to a request. The parameter is set as an array where the key is the field to sort by and the value is the direction of sort, either ASC or DESC. In the example below the results are first sorted by the schema's label and then sorted by the schema creation timestamp.

GET /api/3/customObjects/schemas?orders[labels.singular]=ASC&orders[createdTimestamp]=DESC

Please note that in order to sort records by specific field on that record you will have to define what field you want to order by using the field ID. For example, if you have a record stripe_order that has a field with an ID of amount you would use the following format to order results by that field.

GET /api/3/customObjects/records/1111c1f1-a11a-11a1-1111b-c1abc111ab1c?filters[relationships.primary-contact][eq]=14&orders[fields.my-number-field]=DESC

Filtering

  • filters: All filters will be grouped with AND conditions.

Syntax

Filtering record root level properties

?filters[<root_level_property>][<operator>]=<value>

Example:

?filters[name][contains]=order

Filtering Custom Object fields

?filters[fields.<field_id>][<operator>]=<value>

Example:

?filters[fields.amount][gte]=150

Filtering Custom Object relationships

?filters[relationships.<relationship_name>][<operator>]=<value>

Example:

?filters[relationships.contacts][eq]=123
  • The [] section can be omitted in which case the filter will use the default eq operator

Supported Operators

Operator

Description

eq

Equal

lt

Less than

lte

Less than or equal

gt

Greater than

gte

Greater than or equal

contains

Contains (accepts * as a wildcard)

in

In

is_blank

Mimics "is blank" behavior within platform segmentation UI. Below is a list of what is_blank means for each corresponding field type:

text: empty string OR no value exists
text area: empty string OR no value exists
drop-down: no options present
multi-select: no options present
date: no value exists
date-time: no value exists
number: no value exists
currency: no value exists (for amount)

is_not_blank

Mimics "is not blank" behavior within platform segmentation UI. Below is a list of what is_not_blank means for each corresponding field type:

text: value exists AND not empty string
text area: value exists AND not empty string
drop-down: some sort of option present
multi-select: some sort of option present
date: some sort of non-null value
date-time: some sort of non-null value
number: some sort of non-null value
currency: some sort of non-null value (for amount)