Filtering and Sorting

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

🚧

This functionality is currently in Beta

  • This functionality is only offered on the list endpoint of the Customer object for now, capabilities can change at any time.
  • Please report any unexpected behavior to [email protected]

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 Operators

Operator

Description

Usage

eq

Performs an exact search, effectively returning only results exactly matching VALUE

filter[ATTRIBUTE]=VALUE
filter[ATTRIBUTE]=eq:VALUE
filter[ATTRIBUTE]=eq:VALUE1,VALUE2

oreq

Same as eq, but condition combining the filters will be OR instead of AND

filter[ATTRIBUTE]=oreq:VALUE
filter[ATTRIBUTE]=oreq:VALUE1,VALUE2

like

Performs a fuzzy search, effectively returning any results containing VALUE

filter[ATTRIBUTE]=like:VALUE
filter[ATTRIBUTE]=like:VALUE1,VALUE2

orlike

Same as like, but condition combining the filters will be OR instead of AND

filter[ATTRIBUTE]=orlike:VALUE
filter[ATTRIBUTE]=orlike:VALUE1,VALUE2

has

Determines if a top-level attribute exists in the metadata

filter[metadata]=has:ATTRIBUTE

orhas

Same as has, but condition combining the filters will be OR instead of AND

filter[metadata]=orhas:ATTRIBUTE

Supported Attributes

Endpoint

Attributes

List Customers

email first_name last_name metadata.*

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

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 individual attribute.

To request sorting with Pelcro's API, you can use the sort query parameter in a data retrieval request as follows:

In the above url :

  • ENDPOINT can be any of the supported endpoints,
  • ASCENDINGATTRIBUTE and DESCENDINGATTRIBUTE can be any of the supported attributes detailed in the sections below

Supported Attributes

Endpoint

Sorting Attributes

List Customers

id 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
  • To retrieve all customers sorted by id in an ascending order, and then sorted by created_at in a descending order:, you can use the following URL:
GET https://www.pelcro.com/api/v1/core/customers?sort=id,-created_at