Filters

You can perform the GET and DELETE methods on a subset of resource records. A subset of records can be received by applying filters to some of the resource fields.

Available filters are listed in the Documentation tab of the method’s expanded area, in the Filters section.

To filter, perform the GET request and put your filters parameters in the query string.

Ex 1. Filter in a Query String

Retrieve all users of organization ‘1’.

Request

GET /api/users?filter[organization]=1 HTTP/1.1

Similar to a field, a filter declares a data type and only takes specific values in the input.

Below are examples of requests and errors.

Ex 2. Wrong Input Type

A string value is passed as an input to a filter which can contain only integer values.

GET /api/users?filter[id]=aaa HTTP/1.1

{ "errors": [{
  "status": "400",
  "title": "unexpected value exception",
  "detail": "Expected integer value. Given \"aaa\".",
  "source": {
    "parameter": "filter[id]"
  }
}] }

Ex 3. Unknown Filter

Unknown, mistyped or unsupported filter.

GET /api/users?filter[unknown]=aaa HTTP/1.1

{ "errors": [{
  "status": "400",
  "title": "filter constraint",
  "detail": "Filter \"filter[unknown]\" is not supported.",
  "source": {
    "parameter": "filter[unknown]"
  }
}] }

The API enables you to use several types of filters. Filter types are briefly described in the table below.

Filter	Usage Example	Description
fields	fields[owner]=id,name	Used for limiting the response data only to specified fields. Depends on the include filter if the filter is applied to a relation.
filter	filter[id]=1 or filter[id]=5,7 or filter[id][gt]=8&filter[name]=a or filter[id][neq]=8 or filter[id]=5..7	Used for filtering the response data by specific values of a specific field. A filter is specified using the syntax “key[operator_name]=value”. The full list of supported operators is described in the Data Filter (filter) section. The equality operator (eq) is optional and can be omitted, so the following filters are the same: filter[id]=1 and filter[id][eq]=1. May accept several values separated by comma. In such case, they will be considered connected by the logical OR operator, e.g. filter[id]=5,7 represents the following expression: id = 5 OR id = 7. May accept a data range. The syntax is “from_value..to_value”. The range is inclusive (i.e. it includes the interval boundaries, and the same range can be obtained by executing the following expression: field >= from_value AND field <= to_value). E.g. filter[id]=5..7 represents the following expression: id >= 5 AND id <= 7. And in case of several filters in request, all of them will be perceived as connected using a logical AND operator. E.g. filter[id][gt]=8&filter[name]=a represents the following expression: id > 8 AND name = ‘a’.
include	include=[owner,organization]	Used for inclusion into response the related resources data.
page	page[size]=10&page[number]=1	Used for pagination purposes.
sort	sort=id or sort=id,-name	Used for data sorting. By default the ASC sorting applies. To perform DESC sorting specify `-` before field name.
meta	meta=property1,property2	Used for requesting additional meta properties for API resources.

Fields Filter (fields)

All objects are composed of fields. By default, all fields are returned in API response.

To request particular fields, use the fields filter and specify the fields you need in the response as its values.

Important

We recommend you always to use the fields filter and retrieve only the fields you will use in your application.

Example of Retrieving Only Required Fields

Select the username and the email fields of the users resource.

Request

GET api/users?fields[users]=username,email HTTP/1.1
Accept: application/vnd.api+json

Response

{
  "data": [
    {
      "type": "users",
      "id": "1",
      "attributes": {
        "username": "admin",
        "email": "admin@local.com"
      }
    },
    {
      "type": "users",
      "id": "2",
      "attributes": {
        "username": "sale",
        "email": "sale@example.com"
      }
    }
  ]
}

Data Filter (filter)

Depending on the type of the filter, certain operators are allowed. For example, by default for integer filter type it is allowed to use eight operators: eq, neq, lt, lte, gt, gte, exists, neq_or_null, for string filter type - only four: eq, neq, exists, neq_or_null. The operators contains, not_contains, starts_with, not_starts_with, ends_with, not_ends_with, empty are not allowed by default and should be enabled by a developer who creates API resources.

Operator	Description	Request Example
eq	Equality for fields and to-one associations Contains any of specified element for to-many associations	GET /api/users?filter[id]=1 HTTP/1.1 GET /api/users?filter[id][eq]=1 HTTP/1.1
neq	Inequality for fields and to-one associations Not contains any of specified element for to-many associations	GET /api/users?filter[id][neq]=2 HTTP/1.1
lt	Less than	GET /api/users?filter[id][lt]=3 HTTP/1.1
lte	Less than or equal	GET /api/users?filter[id][lte]=4 HTTP/1.1
gt	Greater than	GET /api/users?filter[id][gt]=5 HTTP/1.1
gte	Greater than or equal	GET /api/users?filter[id][gte]=6 HTTP/1.1
exists	Is not null for fields and to-one associations and is not empty for to-many associations if filter value is true, 1 or yes Is null for fields and to-one associations and is empty for to-many associations if filter value is false, 0 or no	GET /api/users?filter[id][exists]=yes HTTP/1.1 GET /api/users?filter[id][exists]=no HTTP/1.1
neq_or_null	Inequal or is null for fields and to-one associations Inequal or empty for to-many associations	GET /api/users?filter[id][neq_or_null]=test HTTP/1.1
contains	Contains a text for string fields Contains all specified elements for to-many associations	GET /api/users?filter[id][contains]=test HTTP/1.1
not_contains	Not contains a text for string fields Not contains all specified elements for to-many associations	GET /api/users?filter[id][not_contains]=test HTTP/1.1
starts_with	Starts with a text	GET /api/users?filter[id][starts_with]=test HTTP/1.1
not_starts_with	Not starts with a text	GET /api/users?filter[id][not_starts_with]=test HTTP/1.1
ends_with	Ends with a text	GET /api/users?filter[id][ends_with]=test HTTP/1.1
not_ends_with	Not ends with a text	GET /api/users?filter[id][not_ends_with]=test HTTP/1.1
empty	Empty or is null, e.g. an empty string or null, an empty array or null	GET /api/users?filter[id][empty]=yes HTTP/1.1 GET /api/users?filter[id][empty]=no HTTP/1.1

Example of Using Operators to Filter Data

Request

GET /api/users?filter[id][gt]=5$page[number]=1&page[size]=2&fields[users]=username,email HTTP/1.1
Accept: application/vnd.api+json

Response

{
  "data": [
    {
      "type": "users",
      "id": "6",
      "attributes": {
        "username": "jimmy.henderson_c4261",
        "email": "jimmy.henderson_c428e@example.com"
      }
    },
    {
      "type": "users",
      "id": "7",
      "attributes": {
        "username": "gene.cardenas_c760d",
        "email": "gene.cardenas_c7620@yahoo.com"
      }
    }
  ]
}

Inclusion Filter (include)

As mentioned above, the include filter allows you to extend the response data with the related resources information. It is usually used to reduce the number of requests to the server or, in other words, to retrieve all the necessary data in a single request.

All included resources will be represented in included section at the end of the response body.

An included section at the end of the response body

Important

Please note, in case of using fields filter for the main resource (e.g. users), it must contain the field(s) used in the include filter.

Example of Including Related Resources Information

Include the roles relation with the fields filter.

Request

GET api/users?fields[users]=username,email,roles&include=roles&page[number]=1&page[size]=1 HTTP/1.1
Accept: application/vnd.api+json

Response

{
  "data": [
    {
      "type": "users",
      "id": "1",
      "attributes": {
        "username": "admin",
        "email": "admin@local.com"
      },
      "relationships": {
        "userRoles": {
          "data": [
            {
              "type": "userroles",
              "id": "3"
            }
          ]
        }
      }
    }
  ],
  "included": [
    {
      "type": "userroles",
      "id": "3",
      "attributes": {
        "extend_description": null,
        "role": "ROLE_ADMINISTRATOR",
        "label": "Administrator"
      },
      "relationships": {
        "organization": {
          "data": null
        }
      }
    }
  ]
}

Also, it is possible to limit fields that will be retrieved from the relation. For such purposes, the fields filter should be used.

Example of Retrieving Only Required Fields of a Related Resource

Request

GET api/users?fields[userroles]=label&fields[users]=username,email,roles&include=roles&page[number]=1&page[size]=1 HTTP/1.1
Accept: application/vnd.api+json

Response

{
  "data": [
    {
      "type": "users",
      "id": "1",
      "attributes": {
        "username": "admin",
        "email": "admin@local.com"
      },
      "relationships": {
        "userRoles": {
          "data": [
            {
              "type": "userroles",
              "id": "3"
            }
          ]
        }
      }
    }
  ],
  "included": [
    {
      "type": "userroles",
      "id": "3",
      "attributes": {
        "label": "Administrator"
      }
    }
  ]
}

Pagination Filter (page)

By default, the page size is limited to 10 records and the page number is 1. However, it is possible to ask the server to change the page size or page number to get the records that will fit your needs. Pagination parameters should be passed as the parameters of the query string.

Parameter name	Type	Default value	Description
page[size]	integer	10	Set a positive integer number. To disable the pagination, set it as -1. In this case page[number] will not be taken into account and can be omitted.
page[number]	integer	1	The number of the page.

Example of Retrieving a Particular Page of a Paged Response

Get the 2nd page of the retrieved records for the users resource with 20 records per page.

Request

GET /api/users?page[number]=2&page[size]=20 HTTP/1.1
Accept: application/vnd.api+json

Sorting Filter (sort)

When the response to your call is a list of objects, you can also sort this list by using the sort filter with any of the available values listed in the API reference.

Example of Sorting by a Field Value

Sort by username in descending order.

Request

GET /api/users?filter[id][gt]=5$page[number]=1&page[size]=2&fields[users]=username,email&sort=-username HTTP/1.1
Accept: application/vnd.api+json

Response

{
  "data": [
    {
      "type": "users",
      "id": "24",
      "attributes": {
        "username": "william.morrison_247fe",
        "email": "william.morrison_2482c@msn.com"
      }
    },
    {
      "type": "users",
      "id": "31",
      "attributes": {
        "username": "victor.nixon_54050",
        "email": "victor.nixon_5406f@gmail.com"
      }
    }
  ]
}

Meta Property Filter (meta)

The meta filter allows you to request additional meta properties for the resource. Meta properties will be generated for every item and will be returned in the item’s meta object in the response data.

The following table contains a list of supported meta properties that may be requested using ?meta=meta_property_name filter:

Name	Description
title	A text representation of the resource.

Example of Retrieving Text Representation of the Resource

Request

GET api/users?meta=title HTTP/1.1
Accept: application/vnd.api+json

Response

{
  "data": [
    {
      "type": "users",
      "id": "1",
      "meta": {
        "title": "John Doe",
      },
      "attributes": {
        "username": "john.doe",
      }
    },
    {
      "type": "users",
      "id": "2",
      "meta": {
        "title": "Ellen Rowell",
      },
      "attributes": {
        "username": "ellen.rowell"
      }
    }
  ]
}