---
title: Mapping Examples
slug: docs/mapping-examples
createdAt: 2026-07-08T05:53:33.599Z
---

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:

:::BlockQuote
\<\<CANCELLED|true\:true,false\:false>>
:::

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.
