How do I set and update user merge fields with the ESP API?

The endpoint

POST http(s)://api-esp-eu.piano.io/userdata/umfval/pub/<pubid>/set?api_key=<api_key>

Replace api-esp-eu.piano.io with the regional base URL that matches your ESP dashboard (api-esp.piano.io for US, api-esp-ap.piano.io for Asia-Pacific, sandbox-api-esp.piano.io for sandbox).

Set Content-Type: application/json.

The request body

The body is always a JSON array of objects, even when you're updating a single user. Each object is one triple:

[
  { "user": "<id> or <email>", "umf": "<id> or <name>", "value": "<value>" },
  { "user": "<id> or <email>", "umf": "<id> or <name>", "value": "<value>" }
]

You can pass up to 16 objects per call (so up to 16 distinct user/merge-field combinations).

• user accepts either the ESP user ID or the user's email address — whichever you pass, the response will mirror it.

• umf accepts either the merge field's numeric ID or its configured name — same mirroring rule.

• value is the value to set.

On success the endpoint returns HTTP 200. On failure it returns the relevant 4xx/5xx status with an error message.

Common pitfalls

These are the issues that account for nearly every error response the endpoint produces.

Send an array, not a bare object

A single bare object ({ "user": "...", "umf": "...", "value": "..." }) returns HTTP 400 Bad Request. Wrap a single update in an array:

[ { "user": "user@example.com", "umf": "MD5", "value": "test123" } ]

One umf/value pair per object

You cannot nest multiple umf/value pairs inside a single object. To update multiple merge fields for the same user, send multiple objects in the array — one per user/umf pair.

[
  { "user": "user@example.com", "umf": "FIRST_NAME", "value": "Ada" },
  { "user": "user@example.com", "umf": "COUNTRY",    "value": "UK"  }
]

Match the configured field-name casing exactly

If a merge field is configured as ANREDE, sending anrede will produce HTTP 500 Internal Server Error. Field-name matching is case-sensitive. Either use the configured casing or pass the numeric umf ID instead.

Pass numeric IDs as numbers when applicable

When using the numeric umf ID (rather than the field name), pass it as a number, not a string. Sending a string where the API expects a number can produce a 404 response. The same applies to other numeric identifiers in the body.

The user must already exist on a mailing list

You can only set merge fields for users who already belong to at least one mailing list. Calling the endpoint for an unknown or deleted user returns an error. If you're integrating external lead data, subscribe the user to a list first, then set their merge fields.

The merge field must already exist on the site

You cannot create merge fields on the fly through this endpoint. Configure them in the ESP dashboard first; referencing a non-existent merge field returns an error.

List-type fields: pass labels, not IDs

For merge fields of type list (single-select or multi-select):

• Single-select: pass exactly one value, and it must match one of the configured choice labels exactly. A mismatch produces a Failed value validation error.

• Multi-select: pass a JSON array of values, each matching a configured label.

• You cannot create new list items via the API. Choices must be pre-configured in the ESP data field; values that don't match an existing choice are rejected.

Verify environment and site

A mismatched API key or pubid (production key used against sandbox, for example) will produce 4xx errors. Confirm both before debugging payload issues.

A complete example

POST https://api-esp-eu.piano.io/userdata/umfval/pub/4242/set?api_key=YOUR_API_KEY
Content-Type: application/json

[
  { "user": "ada@example.com", "umf": "FIRST_NAME", "value": "Ada"      },
  { "user": "ada@example.com", "umf": "COUNTRY",    "value": "UK"       },
  { "user": "ada@example.com", "umf": "TOPICS",     "value": ["Tech","News"] }
]

This call sets three merge fields on a single user: a text field, a single-select list field, and a multi-select list field.

Deleting merge field values

Use a separate endpoint to delete values:

POST http(s)://api-esp.piano.io/userdata/umfval/pub/<site_id>/delete?api_key=<api_key>
Content-Type: application/json

Body:

{
  "user": "<user_id> | <user_email> | [<user_id>, <user_email>]",
  "umf":  "<umf_id>  | <umf_name>   | [<umf_id>,  <umf_name>]"
}

This call deletes values for up to 16 merge fields across up to 16 users in a single invocation.

Importing external lead data

A common use case is loading data from a CRM, lead-capture form, or import file into ESP user merge fields:

1. Ensure the target user exists in ESP. If not, subscribe them to the appropriate mailing list first via the subscribe endpoint.

2. Make sure the merge fields you want to populate are configured on the site. For list fields, ensure all the values you'll send are configured as choices.

3. Batch your data into groups of up to 16 user/field combinations and POST to the umfval/set endpoint.

4. Check the response for per-row errors and retry or surface failures appropriately.

When sharing API keys for this kind of integration, use a secure channel — keys give full access to the publisher's ESP data.

Updating merge fields from email-link actions

You can drive merge-field updates from a button in an email — for example, a "Click here to confirm your preference" link that updates a custom field when clicked. ESP encodes a data parameter into the link's URL as a Base64 JSON object containing locale, mailing list ID, publisher info, subscriber email, and subscription-management URLs.

To act on it:

1. Decode the Base64 data parameter to extract the subscriber's email and other context.

2. Look up the user in your own database if you need to correlate with internal IDs.

3. Retrieve the Identity Management UID if you're updating a Identity Management custom field (use the Get User Profile or Advanced User Search API by email).

4. Call the appropriate update endpoint — the ESP merge-field endpoint described above for ESP fields, or the Identity Management user-update API for Identity Management custom fields.

5. Validate the request (signature or token) to confirm the click is legitimate before writing.

This pattern is useful for newsletter-preference confirmations and double-opt-in-style flows.

Distinguishing ESP merge fields from email-template variables

Two related concepts often get confused:

• Merge fields (managed via the umfval endpoints) are per-user values used in newsletter campaigns. They are configured per site in the ESP dashboard and personalize content sent to the user.

• Available variables appear in email notification templates and surface system-level values (campaign metadata, transactional context) into transactional email templates.

If a merge field exists in your previous ESP and you want it in Identity Management custom fields, the data must be transferred programmatically — there is no automatic migration. Use the relevant API (the ESP umfval/set endpoint for ESP merge fields, or the Piano publisher user-update endpoint for Identity Management custom fields) to move the data.

Keeping merge fields and email addresses in sync after profile changes

When a user updates their registered email address in Identity Management, that change is not automatically propagated to ESP — neither the mailing-list subscription nor any merge field tied to the old address is updated. To keep them aligned:

1. Detect the change via the /publisher/audit/user API, filtering on action_type=EMAIL_CHANGED. The response contains both previous_value and new_value for the email.

2. Pull the user's existing ESP mailing-list memberships using the subscription status query (iterate over relevant lists).

3. Subscribe the new email to the same set of lists.

4. Re-apply any merge field values to the new email — the umfval/set endpoint accepts the new email and sets the values fresh.

5. Unsubscribe the old email to prevent duplicate sends.

Run this synchronization job on a schedule (for example, nightly). There is no real-time callback for email-address changes, so polling the audit API is the supported pattern today. Take care to respect prior unsubscribes — don't re-subscribe the new email to lists the old email had deactivated from.

This work has to be done server-side: the ESP API key must not be exposed in client-side code.

Troubleshooting

If you're stuck after checking these, contact Piano Support with the full request and response.

Last updated: July 02, 2026