> This page is for Unified.

> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.merge.dev/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.merge.dev/_mcp/server.

# Advanced mapping

> How to use JSONata expressions to transform, filter, or reformat third-party field values before they land on your target fields.

---

## Overview

Advanced mapping allows you to apply transformation logic to a remote field's value before it is written to a target field -- useful when the raw data from a third-party system doesn't match the format or structure your product expects.

In a standard field mapping, the remote field value is passed through as-is. In an advanced field mapping, a JSONata expression is evaluated first, and the result is what gets mapped to the target field.

As illustrated above, advanced mappings let you shape data to fit your product's needs before it lands in the target field.

## Supported transformations

Advanced mapping uses [JSONata](https://docs.jsonata.org/overview) as its transformation language. Any expression supported by JSONata can be used. Common transformation types include:

* **Conditional logic** — Return different values based on a condition. For example, return `annual_salary + bonus` if `employment_type` is `FULL_TIME`, otherwise return just `annual_salary`.
* **Boolean output** — Derive a true/false value from a field or combination of fields. For example, return `true` if `employment_type` is `FULL_TIME`, otherwise `false`.
* **Mathematical operations** — Perform calculations on numeric fields. For example, multiply `pay_rate` by 12 to derive `annual_salary`.
* **String manipulation** — Combine or reformat text fields. For example, concatenate `first_name` and `last_name` into a single `full_name` field.
* **Date formatting** — Reformat date strings to match a required format. For example, convert an ISO timestamp to a date-only string like `2024-03-15`.

## Setup

Advanced mapping can be configured from the Merge dashboard or programmatically via the [Field Mappings API](https://docs.merge.dev/merge-unified/hris/linked-account/field-mapping).

1. In your Merge dashboard, navigate to a Linked Account and open the Field Mapping tab.
2. Create a new field mapping and select the remote field you want to transform.
3. Click **Add advanced mapping** and enter a JSONata expression directly, or use the [AI assisted transformation](https://docs.merge.dev/merge-unified/supplemental-data/field-mapping/ai-data-transformations) to generate one from a prompt.

4) Review the evaluated result against the remote field's sample data, then click Next.
5) Save the field mapping and [access mapped data](https://docs.merge.dev/merge-unified/supplemental-data/field-mapping/access-mapped-data) from Common model responses.