Filtering and Sorting Related Data Records

The GET /relatedData/getRecordsByKey endpoint can return a narrowed and ordered result set. It accepts three optional query parameters: filter, sort_field and sort_order. This page describes their syntax.

All three parameters are optional. If none of them is supplied, the endpoint returns the full result set, exactly as before.

Note

This page covers only the filter query parameter of the Related Data GET endpoint. It is not the RelatedDataFilter object used in the request body of the create, update and delete endpoints, which is a list of name and value pairs that are always combined with AND. It is also not the template functions used for personalization and segmentation, which are described in Functions for Filtering Related Data Sets.

Filter Syntax

A filter consists of one or more conditions. Each condition has the form field operator value.

filter=store=Rome

The filter is applied after the records have been selected by key. It never widens the result set, it only narrows it.

Supported Operators

Using a comparison operator on a String field, or contains on a Number or Date field, returns a validation error.

Combining Conditions

Conditions are combined with AND and OR. Both keywords can be written in any capitalization.

filter=store=Rome AND points>=60

AND is evaluated before OR. The following filter therefore returns all records from Milan, plus those records from Rome that also have at least 60 points.

filter=store=Milan OR store=Rome AND points>=60

Note

Parentheses are not supported. To express a condition such as "store is Milan or Rome, and points are at least 60", repeat the second condition for each alternative: store=Milan AND points>=60 OR store=Rome AND points>=60.

Field Names

Field names are not case-sensitive. store, Store and STORE all address the same field.

A field name that does not exist in the related data set returns a validation error.

Values

On String fields, the = operator compares values exactly, including capitalization. A filter for store=rome does not return records that are stored as Rome.

The contains operator ignores capitalization. A filter for store contains rom returns records stored as Rome.

Values that contain a space or an operator character must be enclosed in double quotation marks. Without the quotation marks, the value is read as the start of the next condition.

filter=store="New York"

Boolean Values

Boolean fields are filtered with true or false. These values are not case-sensitive, so TRUE works as well. Any other value returns a validation error.

filter=subscribed=true

Records Without a Value

A field can be empty in a record, for example because it was never filled during import. The != operator treats such a record as not equal to the given value, so it is returned.

filter=campaign!=summer

The filter above returns every record whose campaign is not summer, including records in which the campaign field is empty. If the field has a default value configured in the related data set, that default is compared instead.

The other operators are not affected. A record with an empty field is not returned by =, by a comparison operator or by contains.

Date and Timestamp Values

Date values must be written in ISO 8601 format, either as a date or as a timestamp with a UTC offset.

The format 10.01.2026, which is accepted when data is imported, is not accepted in a filter.

To select a period, combine two conditions on the same field.

filter=purchased>=2026-01-01 AND purchased<2026-02-01

Sorting

The sort_field parameter defines the field the records are sorted by. Sorting is applied after filtering. Only one sort field is supported, and field names are not case-sensitive.

The sort_order parameter defines the direction. It accepts the values asc, ascending, desc and descending.

Examples

All parameter values must be URL-encoded by the client. The request uses the same authentication as every other Engage REST API request.

The following request returns the purchases of one customer in the Rome store with at least 60 points, sorted by purchase date, most recent first.

curl -G "https://<host>/core/<system>/api/rest/v20/relatedData/getRecordsByKey" \
  --data-urlencode "datasetName=purchases" \
  --data-urlencode "key=customer@example.com" \
  --data-urlencode "filter=store=Rome AND points>=60" \
  --data-urlencode "sort_field=purchased" \
  --data-urlencode "sort_order=desc"

The same request as an encoded URL:

/core/<system>/api/rest/v20/relatedData/getRecordsByKey?datasetName=purchases&key=customer%40example.com&filter=store%3DRome%20AND%20points%3E%3D60&sort_field=purchased&sort_order=desc

Error Responses

The request returns a validation error if the filter cannot be evaluated. This is the case for invalid filter syntax, for unknown field names, for operators that do not exist or are not allowed for the field type, and for invalid sorting values.

The response contains a client error of the type INVALID_PARAMETER and names the parameter, the value and the reason. For the general structure of error responses, see Error Handling.

More Information

• Get related data records by key: the full endpoint reference, including all parameters and response formats.

• Manage Related Data Sets: field names, data types and default values of a related data set.

• Functions for Filtering Related Data Sets: filtering related data in message content, personalization rules and audience selection.