> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mapp.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Get related data records by key
> Returns all related data records stored under the specified key in a related data set.
Optional filter, sort_field and sort_order query parameter values must be URL-encoded by REST clients.
Recommended curl pattern:
curl -G "https://host/core/sysname/api/rest/v20/relatedData/getRecordsByKey" --data-urlencode "datasetName=products" --data-urlencode "key=test-user@example.com" --data-urlencode "filter=NEGOZIO=Rome AND RECEIPTPOINTS>=60" --data-urlencode "sort_field=RECEIPTPOINTS" --data-urlencode "sort_order=desc"
Encoded URL example:
/core/sysname/api/rest/v20/relatedData/getRecordsByKey?datasetName=products&key=test-user%40example.com&filter=NEGOZIO%3DRome%20AND%20RECEIPTPOINTS%3E%3D60&sort_field=RECEIPTPOINTS&sort_order=desc
Response body example - 1 record:
[
{
"datasetName": "products",
"key": "test-user@example.com",
"data": [
{ "name": "hairColor", "value": "green" },
{ "name": "eyeColor", "value": "blue" }
]
}
]
Response body example - empty result:
[]
## OpenAPI
````json GET /relatedData/getRecordsByKey
{
"openapi": "3.0.4",
"info": {
"title": "Engage public API",
"version": "1"
},
"servers": [
{
"url": "https://your-engage-domain.com/api/rest"
}
],
"tags": [
{
"name": "Address Attributes"
},
{
"name": "Async"
},
{
"name": "Audit Log"
},
{
"name": "Automation"
},
{
"name": "Blacklist"
},
{
"name": "CMS"
},
{
"name": "Contact"
},
{
"name": "Content"
},
{
"name": "Coupon"
},
{
"name": "Draft Message"
},
{
"name": "Ecommerce"
},
{
"name": "Group"
},
{
"name": "Group Attributes"
},
{
"name": "Landing Page"
},
{
"name": "Member Attributes"
},
{
"name": "Membership"
},
{
"name": "Message"
},
{
"name": "Meta"
},
{
"name": "Mobile Push"
},
{
"name": "Prepared Message"
},
{
"name": "Process"
},
{
"name": "Profile Attributes"
},
{
"name": "Related Data"
},
{
"name": "Segmentation"
},
{
"name": "System"
},
{
"name": "System User"
},
{
"name": "Usage Statistics"
},
{
"name": "User"
},
{
"name": "Whiteboard"
}
],
"paths": {
"/relatedData/getRecordsByKey": {
"get": {
"tags": [
"Related Data"
],
"summary": "Get related data records by key",
"description": "Returns all related data records stored under the specified key in a related data set.
Optional filter, sort_field and sort_order query parameter values must be URL-encoded by REST clients.
Recommended curl pattern:
curl -G \"https://host/core/sysname/api/rest/v20/relatedData/getRecordsByKey\" --data-urlencode \"datasetName=products\" --data-urlencode \"key=test-user@example.com\" --data-urlencode \"filter=NEGOZIO=Rome AND RECEIPTPOINTS>=60\" --data-urlencode \"sort_field=RECEIPTPOINTS\" --data-urlencode \"sort_order=desc\"
Encoded URL example:
/core/sysname/api/rest/v20/relatedData/getRecordsByKey?datasetName=products&key=test-user%40example.com&filter=NEGOZIO%3DRome%20AND%20RECEIPTPOINTS%3E%3D60&sort_field=RECEIPTPOINTS&sort_order=desc
Response body example - 1 record:
[
{
\"datasetName\": \"products\",
\"key\": \"test-user@example.com\",
\"data\": [
{ \"name\": \"hairColor\", \"value\": \"green\" },
{ \"name\": \"eyeColor\", \"value\": \"blue\" }
]
}
]
Response body example - empty result:
[]
",
"operationId": "getRecordsByKey",
"parameters": [
{
"name": "datasetName",
"in": "query",
"description": "Name of the related data set",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "key",
"in": "query",
"description": "Key defining which record(s) to select from the data set",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "filter",
"in": "query",
"description": "Optional query-string filter expression applied after selecting records by key; it is different from the name/value request-body filter used by Related Data create, update and delete operations. Syntax: field operator value, with conditions combined using AND and OR; AND has higher precedence than OR. Field names are case-insensitive. Supported operators: = and != for typed equality and inequality on all field types; String equality comparisons are case-sensitive, while Boolean literals true and false are case-insensitive. The != operator also matches records where the field is unset, unless the field has a configured default equal to the comparison value. The operators >, >=, < and <= are supported for Number and Date fields; contains performs case-insensitive substring matching on String fields. Date literals use ISO-8601 date or UTC timestamp format, for example 2026-01-10 or 2026-01-10T08:00:00Z. Quote values containing spaces or operator characters, for example store=\"New York\". REST clients must URL-encode this value.",
"schema": {
"type": "string"
}
},
{
"name": "sort_field",
"in": "query",
"description": "Optional active related data field used to sort matching records after filtering. Field names are case-insensitive. Only one sort field is supported. REST clients must URL-encode this value.",
"schema": {
"type": "string"
}
},
{
"name": "sort_order",
"in": "query",
"description": "Optional sort direction for sort_field: asc, ascending, desc or descending. Defaults to ascending when sort_field is supplied. It is ignored when sort_field is omitted. REST clients must URL-encode this value.",
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "successful operation",
"content": {
"application/json": {
"schema": {
"type": "array",
"items": {
"$ref": "#/components/schemas/RelatedDataRecord"
}
}
}
}
},
"400": {
"description": "Invalid filter or sorting input. The response contains a client INVALID_PARAMETER error with parameterName, value and message details.",
"content": {
"application/json": {}
}
}
}
}
}
},
"components": {
"schemas": {
"RelatedDataRecord": {
"type": "object",
"properties": {
"datasetName": {
"type": "string"
},
"key": {
"type": "string"
},
"data": {
"type": "array",
"items": {
"$ref": "#/components/schemas/Attribute"
}
}
}
},
"Attribute": {
"type": "object",
"properties": {
"name": {
"type": "string"
},
"value": {
"type": "string"
}
}
}
}
}
}
````