Reshape values with transformers and value mappers

This article shows how to send a buyer data in the shape it demands without changing what your suppliers send you. Two tools do the work, and they run in that order.

A value mapper swaps whole values on a field, for example CA becomes California. A transformer reshapes a value inline in the delivery template, for example formatting a phone number or a date.

Which one to use

Value mappers run first, so a transformer always sees the already-mapped value.

Set up a value mapper

1. Go to Campaigns, open the campaign, and open the Buyers tab.
2. Open the buyer and click Value Mapper.
3. Add a mapper and set the Key Name to the campaign field it applies to.
4. Under Value Replacements, add each pair: the value that arrives, and the value the buyer wants instead.
5. Click Save Mapper.
6. Run Test Integration and confirm the payload carries the replaced values.

Mappers are per buyer, so two buyers on the same campaign can receive two different vocabularies for the same field.

Use transformers in a template

Anywhere you write a delivery template, a shortcode pulls a field in:

{{first_name}}

Add a transformer with || after the field name, and parameters after a colon:

{{phone||phone:10}}
{{dob||date:Y-m-d@@d/m/Y||age}}
{{state||uppercase}}

Transformers chain left to right, so each one receives the output of the last.

What is available

The library is large. These are the ones you will reach for most.

The full list, with the exact syntax for each, is in the shortcode reference beside the template editor.

Leave a key out when the value is empty

if_exists removes the whole key rather than sending an empty one:

{
  "required_field": "{{first_name}}",
  "optional_field": "{{middle_name||if_exists}}"
}

If middle name is empty, the buyer never sees that key at all.

Arrays

Array values are turned into a JSON string before transformers run. iterate_array applies the transformers that follow it to each element, and a collapse transformer turns the result back into what the buyer wants:

{{roof_type||iterate_array||uppercase||json_array_to_csv}}

That takes a list of roof types and sends CEILING,TIN.

Values that are not lead fields

Some shortcodes generate or look up a value rather than reading the payload.

The three system values are generated once per delivery and frozen, so the same value appears everywhere in that delivery and on its retries.

On a multi-step ping, a later step can read an earlier step's response with {{$ping_step_1:data.field_name}}. Only steps before the current one are offered in the editor.

Custom headers

Headers use single braces rather than double, and take payload fields directly:

Authorization: Bearer {api_key}
X-Lead-ID: {lead_id}
X-Zip: {address.zip}

{lead_id} and {lead_utc_date} are fixed tokens. Everything else is a payload field, and dot notation reaches nested values. Header names accept letters, digits, hyphens, underscores and dots only.

Expected result

Test Integration on the buyer produces a payload in exactly the shape the buyer asked for, with replaced values, formatted dates and phone numbers, and no empty optional keys.

Troubleshooting

• A shortcode came through as literal text. The field name does not match a campaign field exactly. Check spelling and case.
• A transformer did nothing. The name is wrong or the parameters are malformed. Check it against the shortcode reference.
• if_exists did not remove the key. The field holds an empty string rather than nothing at all. Empty is not the same as absent, so fix it at the source or add a fallback.
• A value mapper is not applying. It is attached to a different buyer, or its key name does not match the field.
• A header placeholder is empty. The field is not in the payload for that lead, or it is null.
• A ping step reference is empty. The step number is wrong, or that step's response did not contain the path you asked for.