Data Search Step

The Data Search step lets you query one or more of your organization's datasets during a workflow. You define what to search for, how results are selected (automatically or by the user), and which fields to display. The selected record is then available for mapping in later steps.

Datasets

A Data Search step contains one or more dataset configurations.

Setup

The setup object defines how the dataset is queried and how a result is selected.

Selection modes

• AUTOMATIC: The first matching record is selected without user input.
• MANUAL: The user chooses from the matching results before the workflow continues.

Search criteria

Search criteria define how results are filtered and sorted.

Linked entity filters

Datasets can include more than one entity — for example, an "Account & Contacts" dataset might have Accounts as the primary entity and Contacts as a linked entity. primarySearchCriteria filters the primary entity. linkedEntitiesFilters lets you apply additional search criteria to each linked entity in the dataset.

linkedEntitiesFilters is a plain object where:

• Each key is the linkId of a linked entity, as found in the dataset's linkAliases array (returned by GET /v1/activation/dataset/{datasetId}).
• Each value is a search criteria object with the same structure as primarySearchCriteria — sortFieldId, sortDirection, joinLogic, and filters. The fieldId values inside filters must belong to that linked entity, not the primary entity.

If the dataset has no linked entities, or you do not need to filter them, pass an empty object: "linkedEntitiesFilters": {}.

Filters

Each filter narrows the search to records that match a specific condition.

Operators

The available operators depend on the scalar type of the field being filtered. You can check the field's type from the Data Catalog field endpoints.

• EQUALS: Exact match. Available for all field types.
• NOT_EQUALS: Not equal to the value. Available for all field types.
• CONTAINS: Field value contains the string as a substring. Available for text fields only.
• STARTS_WITH: Field value begins with the string. Available for text fields only.
• ENDS_WITH: Field value ends with the string. Available for text fields only.
• GREATER_THAN: Field value is greater than the filter value. Available for number, date, and time fields.
• GREATER_THAN_OR_EQUALS: Greater than or equal. Available for number, date, and time fields.
• LESS_THAN: Field value is less than the filter value. Available for number, date, and time fields.
• LESS_THAN_OR_EQUALS: Less than or equal. Available for number, date, and time fields.

Results

The results object controls how matching records are presented.

Results fields

Examples

Let's start with the simplest valid setup: one dataset, automatic selection, no filters, and all fields shown by default.

{
  "datasets": [
    {
      "datasetId": "ds1b2c3d-e5f6-7890-1234-567890abcdef",
      "setup": {
        "required": true,
        "selectionMode": "AUTOMATIC",
        "primarySearchCriteria": {
          "sortFieldId": "f1b2c3d4-e5f6-7890-1234-567890abcdef",
          "sortDirection": "ASCENDING",
          "joinLogic": "AND",
          "filters": []
        },
        "linkedEntitiesFilters": {}
      },
      "results": {
        "showConfirmationPage": false,
        "tableMode": "DEFAULT",
        "fields": []
      }
    }
  ]
}

Building on that, here's a more complete example with multiple filters (including a mapped value from a previous form step), a linked entity filter, manual selection, and a custom results table.

{
  "datasets": [
    {
      "datasetId": "ds2b3c4d-e5f6-7890-1234-567890abcdef",
      "setup": {
        "required": true,
        "selectionMode": "MANUAL",
        "primarySearchCriteria": {
          "sortFieldId": "f2b3c4d5-e5f6-7890-1234-567890abcdef",
          "sortDirection": "ASCENDING",
          "joinLogic": "AND",
          "filters": [
            {
              "fieldId": "f3c4d5e6-e5f6-7890-1234-567890abcdef",
              "operator": "EQUALS",
              "value": "{{`Form`.`email`}}"
            },
            {
              "fieldId": "f4d5e6f7-e5f6-7890-1234-567890abcdef",
              "operator": "EQUALS",
              "value": "active"
            },
            {
              "fieldId": "f5e6f7a8-e5f6-7890-1234-567890abcdef",
              "operator": "GREATER_THAN_OR_EQUALS",
              "value": "2024-01-01"
            }
          ]
        },
        "linkedEntitiesFilters": {
          "l1b2c3d4-e5f6-7890-1234-567890abcdef": {
            "sortFieldId": "f6f7a8b9-e5f6-7890-1234-567890abcdef",
            "sortDirection": "DESCENDING",
            "joinLogic": "OR",
            "filters": [
              {
                "fieldId": "f7a8b9c0-e5f6-7890-1234-567890abcdef",
                "operator": "NOT_EQUALS",
                "value": "cancelled"
              },
              {
                "fieldId": "f8b9c0d1-e5f6-7890-1234-567890abcdef",
                "operator": "GREATER_THAN",
                "value": "100"
              }
            ]
          }
        }
      },
      "results": {
        "showConfirmationPage": true,
        "tableMode": "CUSTOM",
        "fields": [
          { "fieldId": "f9c0d1e2-e5f6-7890-1234-567890abcdef", "customLabel": "Customer ID" },
          { "fieldId": "f0d1e2f3-e5f6-7890-1234-567890abcdef", "customLabel": "First Name" },
          { "fieldId": "f2b3c4d5-e5f6-7890-1234-567890abcdef", "customLabel": "Last Name" },
          { "fieldId": "f3c4d5e6-e5f6-7890-1234-567890abcdef", "customLabel": "Email Address" },
          { "fieldId": "f4d5e6f7-e5f6-7890-1234-567890abcdef", "customLabel": "Phone Number" }
        ]
      }
    }
  ]
}