Advanced Field Mapping with JMESPath
Deprecation Notice
JMESPath use in Advanced Field Mapping was deprecated in March 2026. Your existing mappings with JMESPath will keep working, but we recommend migrating to JSONata - a more powerful replacement that does everything JMESPath does, and a lot more. Learn more here
Overview
Merge Field Mapping allows you or your users to map data from your users' platforms to new fields on your Merge Common Models. This way you can access custom fields from third-party platforms that Merge does not normalize.
Advanced Field Mapping is a feature enhancement that allows you to write JMESPath queries to access specific values from a list of objects.
How to access Advanced Mapping
In your Merge Dashboard, go to a Linked Account.
Click into the Field Mapping Tab to create a new Field Mapping.
When you are selecting from the remote fields dropdown, you will see the "Advanced Mapping" option appear for any fields of type "List".
Expanding Advanced Mapping will allow you to view the full remote field
From here, you may use the query input field to write JMESPath queries to select specific fields in this List
If you want to select fields in the List using its index, you can simply click the value that you care about, and we will auto-generate the query!
JMESPath Basics
You can specify queries using JMESPath.
Index Expressions allow you to select a specific element in a list. It should look similar to array access in common programming languages. Indexing is 0 based.
Functions can also be combined with filter expressions. In the example below, the JMESPath expression finds all elements in myarray that contain the string foo.
Common Query Examples
In the following example, we want to get a personal email
[{ "emailUri": "[email protected]",
"nameCode": { "codeValue": "Personal E-mail", "shortName": "Personal E-mail" }, "notificationIndicator": false }]You can generate the query using ChatGPT! Try asking:
"Get the email URI only if shortName is Personal E-mail using jmespath and share only the snippet and the outputted value"
To get the emailUri by index: "[0].emailUri"
To get the emailUri only if shortName is Personal E-mail: [?nameCode.shortName == 'Personal E-mail'].emailUri | [0]
We’ve put together a list of commonly requested JMESPath queries. You may need to log in to the Help Center using your work email address to view it.
Quotes Matter
Make sure to only double-quote variable names, and single-quote or back-tick-quote anything that is a string literal. This requirement is inconsistent with normal python comparisons. The behavior is strict and unintuitive to people unfamiliar with jmespath. Learn more here.