​
Data Reference formatting options

When referencing data in Next Matter, you have three formatting options to choose from depending on your use case:
  • JSON: Preserves the original data structure with proper escaping for system integration
  • Plain: Provides human-readable format for display purposes
  • JSON first result: Extracts the first item from arrays or first character from strings. This formatting option is available for:
    • user variables (information coming from integration steps)
    • webhook variables (information coming from the webhook payload)

​
When to use each format

JSON format: Use when the data is used in other Next Matter steps or to complete integration, as most systems parse and understand this format. Plain format: Use when you want the data to be provided in a human-readable format to display it to users. JSON first result: Use for webhook and user variables when you need to remove unwanted array wrapping from API responses or extract the first element from lists. This is particularly useful for:
  • API responses that return single values wrapped in brackets: ["value"] → "value"
  • Extracting the first item from arrays: [1, 2, 3] → 1
  • Building clean JSON request bodies without brackets
We use JSONPath for extracting values from JSON responses. The structure of returned data can vary depending on the data source. We recommend testing each integration to determine which reference method (JSON or JSON first result) works best as the optimal approach depends on the data structure and requirements.

​
Differences in formats

In the case of the input types that are not listed here, both options look the same.

​
Text and String Input

This is an example text with linebreaks\n\nand \"double quotes\"

​
Multi-value dropdowns and checklists

The examples are based on the itemsSelected and itemsChecked references. All other references for these inputs look the same. 
["Option A", "Option B"]

​
File and image uploads

The examples are based on the “files” and “images” reference. In the case of the firstFile reference, there is no difference between this reference and JSON first result. 
["https://file1.com", "https://file2.com"]

​
User variables and Webhook variables

JSON first result is specifically designed for user variables and webhook variables that often contain API response data. 
[{"user_id": 123, "name": "John"}]

["user123", "user456"]

​
Tables

If you want to use table values as a data reference, you have the following options:
  • Plain and JSON formats can be selected in the Body of Integration steps
  • JSON format can be selected in other fields (for example, form fields, or email messages)
There is no difference between JSON (other fields) and plain. The JSON that can be selected in the Body field contains escaped values. The code example contains example values. 
[[\"ONE\",\"Blue\"],[\"TWO\",\"Yellow\"],[\"ONE\",\"Blue\"],[\"TWO\",\"Yellow\"]]
To send JSON table output to a Google Sheet using a custom integration, you must first parse the JSON to convert it from a string into a structured format. Currently, you cannot use the output in the Google Sheets no-code step.

​
JSON first result - Important notes

JSONPath internally stores everything as arrays. The JSON first result function operates in a simple two-step process. First, it examines the JSON value (as displayed in the JSON column) and then takes the first item of the array stored.

​
Examples

JSONPathSample JSONJSON first result outputJSONPlain
$.values{ "values": [1, 2, 3] }[1,2,3][[1,2,3]]1,2,3
$.users[*].id{ "users": [{"id": 1}, {"id": 2}] }1[1,2]1,2
${ "a": 1 }{ "a": 1 }[{ "a": 1 }]{ a: 1 }
Non-existent path$.missingnull[]
$.active{ "active": true }true[true]true
$.[*][{"user_id": 123, "name": "John"}]{"user_id": 123, "name": "John"}[{"user_id": 123, "name": "John"}]{"user_id": 123, "name": "John"}

​
How it works in practice