Sorting and filtering

Sorting and filtering capabilities enables you to build complex queries in order to find exactly what you are looking for.

🚧

This functionality is currently in Beta

Sorting

When you retrieve or filter resources through our APIs, you can return sorted data. Data can be sorted by one or more attributes. The sorting direction can be either ascending (default) or descending for each of the supported attributes.

Supported endpoints and attributes

EndpointAttributes
List customersid email

Examples

To retrieve all customers sorted in an ascending order by their email addresses, you can use the following URL:

GET https://www.pelcro.com/api/v1/core/customers?sort=email

To retrieve all customers sorted in an descending order by their email addresses, you can use the following URL:

GET https://www.pelcro.com/api/v1/core/customers?sort=-email

Filtering

When requesting a list of resources through our APIs, you can search and get only the results you want by adding special filters to the query parameters using the following format:

GET https://www.pelcro.com/api/v1/core/customers?filter[ATTRIBUTE]=(OPERATOR):?VALUE

In the above url :

  • ATTRIBUTE can be any attribute detailed in the sections below,
  • OPERATOR is an allowed operator for this ATTRIBUTE,
  • VALUE is the value you would like to search for

Searching works by adding filters for supported attributes for the given resource endpoint, and by specifying an operator with a value to use. Adding an operator is optional; if not specified, it always defaults to the eq operator.

Supported endpoints and attributes

EndpointAttributes
List customers email first_name last_name metadata.*

Supported operators

OperatorDescriptionUsage
eqPerforms an exact search, effectively returning only results exactly matching VALUEfilter[ATTRIBUTE]=VALUE
filter[ATTRIBUTE]=eq:VALUE
filter[ATTRIBUTE]=eq:VALUE1,VALUE2
oreqSame as eq, but condition combining the filters will be OR instead of ANDfilter[ATTRIBUTE]=oreq:VALUE
filter[ATTRIBUTE]=oreq:VALUE1,VALUE2
likePerforms a fuzzy search, effectively returning any results containing VALUEfilter[ATTRIBUTE]=like:VALUE
filter[ATTRIBUTE]=like:VALUE1,VALUE2
orlikeSame as like, but condition combining the filters will be OR instead of ANDfilter[ATTRIBUTE]=orlike:VALUE
filter[ATTRIBUTE]=orlike:VALUE1,VALUE2
hasDetermines if a top-level attribute exists in the metadatafilter[metadata]=has:ATTRIBUTE
orhasSame as has, but condition combining the filters will be OR instead of ANDfilter[metadata]=orhas:ATTRIBUTE

Examples

To retrieve all customers having articles in metadata as a top-level attribute, you can use the following filter:

GET https://www.pelcro.com/api/v1/core/customers?filter[metadata]=has:articles

To retrieve all customers having a top-level metadata attribute of old_id equal to 22288, this is the filter you would use:

GET https://www.pelcro.com/api/v1/core/customers?filter[metadata.old_id]=eq:22288

To retrieve all customers having first names containing the string Audra, you can use the following filter:

GET https://www.pelcro.com/api/v1/core/customers?filter[first_name]=like:Audra

To retrieve all customers having emails containing either John OR mysite.com, you can use the following filter:

GET https://www.pelcro.com/api/v1/core/customers?filter[email]=like:John,mysite.com

Combining filters

Of course, you can combine as many filters as you want on different attributes. Let's take a look at some examples:

Note that the combination of primary filters in the above example is effectively doing a series of AND requests. This means that if any of the filters using those operators return an empty result, you will receive a 404 Not Found HTTP status code, regardless of whether other filters do match valid results. For more flexibility during searching, you can add OR operators to your filters.

As an example, if you want to fetch all customers having a first name containing either Jane orJohn, OR having a last name containing the string Doe, OR having an email on Gmail:

GET https://www.pelcro.com/api/v1/core/customers?filter[first_name]=like:Jane,John&filter[last_name]=orlike:Doe&filter[email]=orlike:gmail.com

Expected behaviors and limitations

Please note that the following are currently in effect when using the filter query parameter:

  • All searches are case-insensitive
  • When no operator is specified on any given filter, the default is always eq
  • Filters must contain at least one primary operator. Primary operators are eq, like and has
  • The has or orhas operators can only by used against metadata, only on top level-attributes
  • For metadata search, like and orlike operators are not supported
  • Multiple filters for the same attribute cannot be detected, hence is not supported
  • When combining an or operator with any other primary operators, filters are independent of one another, meaning you will get the results of both filters