Mapping Examples
These mapping examples are worked examples for each resource type. Each one is a complete template you can copy and adapt: change the field names to match what your consumer expects, keep the merge tags that supply the values, and you have a starting point rather than a blank page.
How mappings work
A mapping is a template describing the payload you want out. Each value is a merge tag that the endpoint replaces at send time:
- "first_name": "<<FIRST_NAME>>" produces "first_name": "Ada".
- List-valued tags such as <<CUSTOM_FIELDS_LIST|format:json>> and <<CATEGORIES_LIST|...>> emit a JSON array or object inline.
- Boolean tags such as <<CANCELLED|true:true,false:false>> map a true/false value to the text emitted for each case (see Value mapping below).
You choose the key names. The merge tag on the right supplies the value; the key on the left is whatever your consumer expects to receive.
Quoting
Follow one rule when writing a template:
- Tags that emit plain text (<<FIRST_NAME>>, <<EMAIL>>, and so on) go inside quotes: "email": "<<EMAIL>>".
- Tags that emit a JSON value (<<CUSTOM_FIELDS_LIST|format:json>>, <<CATEGORIES_LIST|...>>) go without quotes so the value sits inline: "custom_fields": <<CUSTOM_FIELDS_LIST|format:json>>.
Each article notes which of its tags are plain-text and which are JSON.
Value mapping
A | after the tag name introduces options. For boolean fields, the true: and false: options set the text emitted for each case:
Read this as "if the value is true, emit true; if it is false, emit false." Because the tag is wrapped in quotes, the result is the string "true" or "false", not a native boolean.
The output text is up to you. For example, <<CANCELLED|true:yes,false:no>> emits "yes" or "no" instead.
This true: / false: mapping applies only to fields whose value is true or false. It is not a general find-and-replace for arbitrary text fields, and other tags use their own options (for example format:json). The same true: / false: options also appear inside the <<CATEGORIES_LIST>> tag, where true:applied,false:not_applied sets the label for whether each Category is applied to the Person: still a per-Category true/false underneath.