Supplemental dataField Mapping

Advanced mapping

Transform remote field data using JSONata expressions before mapping to a target field

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.

Advanced field mapping

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 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.

  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 to generate one from a prompt.
Advanced field mapping
  1. Review the evaluated result against the remote field’s sample data, then click Next.
  2. Save the field mapping and access mapped data from Common model responses.