Skip to main content
You can apply filters to GET and DELETE requests to operate on a subset of resource records. Available filters for a resource are listed in the Documentation tab in the Filters section of the API Sandbox.

​
Filter types overview

FilterUsage exampleDescription
fieldsfields[owner]=id,nameLimits response data to specified fields. Depends on the include filter if applied to a relation.
filterfilter[id]=1Filters response data by specific field values. Supports operators.
includeinclude=[owner,organization]Includes related resource data in the response.
pagepage[size]=10&page[number]=1Controls pagination.
sortsort=id or sort=id,-nameSorts results. Prefix with - for descending order.
metameta=titleRequests additional meta properties for each resource item.

​
Fields filter

By default, all fields are returned in the API response. To request only specific fields, use the fields filter.
Always use the fields filter and retrieve only the fields your application needs. This reduces response size and improves performance.
Example: retrieve only username and email 
GET /api/users?fields[users]=username,email HTTP/1.1
Accept: application/vnd.api+json

{
  "data": [
    {
      "type": "users",
      "id": "1",
      "attributes": {
        "username": "admin",
        "email": "[email protected]"
      }
    },
    {
      "type": "users",
      "id": "2",
      "attributes": {
        "username": "sale",
        "email": "[email protected]"
      }
    }
  ]
}

​
Data filter

Use the filter query parameter to filter by field values. The syntax is: 
filter[field_name][operator]=value
The eq operator is the default and can be omitted: filter[id]=1 and filter[id][eq]=1 are equivalent.

​
Supported operators

OperatorDescriptionExample
eqEquality (fields and to-one); contains any specified element (to-many)filter[id]=1
neqInequality (fields and to-one); not contains any specified element (to-many)filter[id][neq]=2
ltLess thanfilter[id][lt]=3
lteLess than or equalfilter[id][lte]=4
gtGreater thanfilter[id][gt]=5
gteGreater than or equalfilter[id][gte]=6
existsNot null / not empty (true, 1, yes); null / empty (false, 0, no)filter[id][exists]=yes
neq_or_nullInequal or null (fields, to-one); inequal or empty (to-many)filter[id][neq_or_null]=test
containsContains text (string); contains all specified elements (to-many)filter[name][contains]=test
not_containsDoes not contain text (string); does not contain all specified elements (to-many)filter[name][not_contains]=test
starts_withStarts with textfilter[name][starts_with]=test
not_starts_withDoes not start with textfilter[name][not_starts_with]=test
ends_withEnds with textfilter[name][ends_with]=test
not_ends_withDoes not end with textfilter[name][not_ends_with]=test
emptyEmpty string or null, empty array or nullfilter[name][empty]=yes
By default, integer filters support: eq, neq, lt, lte, gt, gte, exists, neq_or_null. String filters support: eq, neq, exists, neq_or_null. Operators like contains, starts_with, ends_with, and empty must be explicitly enabled by a developer.

​
Multiple values (OR)

Separate values with a comma to apply logical OR: 
GET /api/users?filter[id]=5,7 HTTP/1.1
This returns users where id = 5 OR id = 7.

​
Range values

Use from_value..to_value syntax for inclusive ranges: 
GET /api/users?filter[id]=5..7 HTTP/1.1
This returns users where id >= 5 AND id <= 7.

​
Multiple filters (AND)

Multiple filter parameters are combined with logical AND: 
GET /api/users?filter[id][gt]=8&filter[name]=a HTTP/1.1
This returns users where id > 8 AND name = 'a'.
You can use the same field with multiple operators: filter[id][gte]=5&filter[id][lte]=7.
Example with operators, pagination, and field selection 
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

{
  "data": [
    {
      "type": "users",
      "id": "6",
      "attributes": {
        "username": "jimmy.henderson_c4261",
        "email": "[email protected]"
      }
    },
    {
      "type": "users",
      "id": "7",
      "attributes": {
        "username": "gene.cardenas_c760d",
        "email": "[email protected]"
      }
    }
  ]
}

​
Include filter

The include filter extends the response with related resource data. This reduces the number of requests needed to fetch all required data. Included resources appear in the included section at the end of the response body.
When using the fields filter on the main resource, it must include the field(s) used in the include filter.
Example: include roles with field selection 
GET /api/users?fields[users]=username,email,roles&include=roles&page[number]=1&page[size]=1 HTTP/1.1
Accept: application/vnd.api+json

{
  "data": [
    {
      "type": "users",
      "id": "1",
      "attributes": {
        "username": "admin",
        "email": "[email protected]"
      },
      "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
        }
      }
    }
  ]
}
You can also limit fields on included resources using the fields filter: 
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

​
Pagination filter

By default, responses are limited to 10 records starting from page 1.
ParameterTypeDefaultDescription
page[size]integer10Number of records per page. Set to -1 to disable pagination.
page[number]integer1The page number to retrieve.
Example: page 2 with 20 records per page 
GET /api/users?page[number]=2&page[size]=20 HTTP/1.1
Accept: application/vnd.api+json

​
Sorting filter

Use the sort parameter with any available field name. Ascending order is the default.
  • Ascending: sort=username
  • Descending: sort=-username
  • Multiple fields: sort=id,-name
Example: sort by username descending 
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

{
  "data": [
    {
      "type": "users",
      "id": "24",
      "attributes": {
        "username": "william.morrison_247fe",
        "email": "[email protected]"
      }
    },
    {
      "type": "users",
      "id": "31",
      "attributes": {
        "username": "victor.nixon_54050",
        "email": "[email protected]"
      }
    }
  ]
}

​
Meta property filter

The meta filter requests additional meta properties for each resource item in the response. Meta properties appear in the item’s meta object.
NameDescription
titleA text representation of the resource.
Example: retrieve title meta property 
GET /api/users?meta=title HTTP/1.1
Accept: application/vnd.api+json

{
  "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"
      }
    }
  ]
}

Build docs developers (and LLMs) love

Get started for freeTalk to us