Query data using RSQL

The REST API Query Language (RSQL) is a super-set of the Feed Item Query Language (FIQL) providing a way for parameterized filtering of entries in RESTful APIs using a clean and simple URI-friendly syntax.

Examples

/contracts?search=(country=='DE',country=='IT');startDate=gt='2023-01-01T00:00:00Z'&size=20&orderBy=startDate&direction=asc

/contracts?search=(country=='DE' or country=='IT') and startDate > '2023-01-01T00:00:00Z'&size=20&orderBy=startDate&direction=desc

Parameters

Our GET-endpoints usually support the following optional parameters:

  • search - the RSQL search query to filter entries by using different search criteria and operators.
  • page - the page number to be returned, starting at 0.
  • size - the number of entries to return for a page. A maximum of 100 is allowed.
  • orderBy - order by criteria
  • direction - direction 'asc' or 'desc' for ordering.

Basic Operators

RSQL offers these basic operators:

Operator (FIQL-style)AlternativeDescription
==(n.a.)Equal To
!=(n.a.)Not Equal To
=gt=>Greater Than
=ge=>=Greater Or Equal To
=lt=<Less Than
=le=>=Less Or Equal To
=in=(n.a.)In
=out=(n.a.)Not in

Multiple operators can be combined by joining them as follows.

Joining Operators

Operator (FIQL-style)AlternativeDescription
;andLogical AND
,orLogical OR

By default, the AND operator takes precedence (i.e. it’s evaluated before any OR operators are). However, a parenthesized expression can be used to change the precedence, yielding whatever the contained expression yields.

Dos and Don'ts when using RSQL

Wrapping and escaping the search

Please ensure to wrap the search parameter to ensure the best result. So search for

?search=orderIdent=='your_order'

instead of

?search=orderIdent==your_order

This also applies if you want to use wild cards - they should be part of the search string too, so

?search=orderIdent=='*order'

❗️

Wildcards currently do not work directly before or after underscores ('_').

Avoid spaces in your query

Please do not use any spaces when not needed, especially no leading or trailing spaces for properties to query for, eg.

?search= orderIdent == 'order123'

should be

?search=orderIdent=='order123'

The other way round using spaces around joining operators such as

?search=orderIdent=='order123' and grossTotal>100

is perfectly fine.

Querying by properties

Properties can be made use of for most of our resources (please check Properties for details), hence they can be targetted in queries as well:

/orders?search=(properties.propertyIdent=='orderChannel';properties.propertyValue=='MERCHANT')

❗️

Querying for multiple properties is currently not supported.