How to update a User's Custom Fields via the API?

Prerequisites

Create and Verify the Custom Field

Before updating any values, ensure the custom field exists in the Piano dashboard under Manage → Custom fields and that you have:

• The exact field key / internal name as defined in Piano

• The correct data type (for example, boolean, date, select/options)

Use a Stable User Identifier (UID Recommended)

Most bulk update workflows are easiest if you have the Piano uid for each user. If you are starting from an email list, first map emails to UIDs using one of the following:

• The Publisher user listing/search capabilities in the dashboard, or

• The API (for example, user listing endpoints) to resolve users and collect uid values

Updating Custom Fields via the API

Custom fields can be updated using the /publisher/user/update endpoint in two ways:

1. In the JSON body

2. In the x-www-form-urlencoded body

The examples below use the Sandbox environment. All available base URLs for Production are listed here.

JSON Body

curl --location \\
  --request POST 'https://sandbox.piano.io/api/v3/publisher/user/update?aid=ykPbwyu8Hn&amp;uid=PNIXBbTI0s1w3uf&amp;api_token=<api_token>&amp;email=ios@sssd.com&amp;first_name=test&amp;last_name=ios' \\
  --header 'Content-Type: application/json' \\
  --data-raw '{ "ba_street_address_1": "test value" }'

You must provide the Content-Type: application/json header and post the body as JSON rather than key-value pairs. For example:

--data '{"field_phone_number": "123456789"}'

x-www-form-urlencoded Body

curl --location --request POST 'https://sandbox.piano.io/api/v3/publisher/user/update' \\
  --header 'Content-Type: application/x-www-form-urlencoded' \\
  --data-urlencode 'aid=ykPbwyu8Hn' \\
  --data-urlencode 'uid=PNIXBbTI0s1w3uf' \\
  --data-urlencode 'api_token=<api_token>' \\
  --data-urlencode 'email=ios@sssd.com' \\
  --data-urlencode 'first_name=test' \\
  --data-urlencode 'last_name=ios' \\
  --data-urlencode 'custom_fields={"ba_street_address_1": "test value1"}'

Custom Field Format Reference

The following formats apply regardless of which request body method you use:

{
  "field_id_boolean": true,
  "field_id_multiselect": "[\"Brazil\",\"Germany\"]",
  "field_id_singleselect": "[\"Canada\"]",
  "field_id_text": "text",
  "field_id_date": "yyyy-mm-dd",
  "field_id_number": "number"
}

Bulk Updates

Bulk Updates via Scripted Loop

The /publisher/user/update endpoint updates one user per request. For bulk updates, loop over your user list in a script (Python, Node.js, etc.).

Typical workflow:

1. Build a list of target users (preferably uid values).

2. For each user, call POST /publisher/user/update with:

   • aid (Application ID)

   • api_token

   • User identifier (for example, uid)

   • Custom field key/value(s) to set

3. Log successes and failures; retry transient errors.

4. Validate a sample of user profiles in Identity Management.

Notes and best practices:

• Rate and latency: Frequent calls to this endpoint can cause latency issues. For very large volumes, consider alternative endpoints referenced in the API documentation or contact your Piano Support team for guidance.

• Exact field keys: The custom field name must match exactly what is configured in Piano (case sensitive).

• Segmentation timing: After updating fields, allow time (up to ~24 hours in some setups) for audience and segmentation computations to reflect the new values.

Using Postman or Similar Tools

If you prefer not to write a full script, you can run bulk updates by:

• Preparing a data file (CSV or JSON) of users and values, and

• Using Postman Collection Runner (or a similar tool) to iterate requests to /publisher/user/update

Bulk User Creation with Custom Fields

If you need to create users in bulk and also populate custom fields:

1. Use the Bulk Users Create tool to upload users (email required; first/last name optional).

2. After users are created, update custom fields using POST /publisher/user/update in a scripted loop as described in this section.

Dynamic Logic (Setting One Field Based on Another)

Piano does not automatically set a custom field based on another field's value. If you need conditional updates:

1. Retrieve the user's existing custom fields using the Identity Management API user retrieval endpoint (for example, /id/api/v1/publisher/users/get).

2. Apply your logic in your backend or script.

3. Update the target field using either:

   • Management + Billing/Publisher API: POST /publisher/user/update, and/or

   • Identity Management API endpoints for custom forms (see the Identity Management API "custom form" section)

Troubleshooting

Custom Field Did Not Update

Check the following:

• The field key/name matches exactly what is defined in Piano.

• The value matches the field's data type and allowed values.

• You are updating the correct user (verify uid exists and belongs to the correct aid).

• Your API credentials are valid (api_token, correct aid).

"User Not Found" or UID Issues

• Confirm the uid is correct and exists in your application.

• If you started from an email list, re-run your mapping from email → UID.

Updates Succeeded but Segments Did Not Change

• Allow time for segmentation and audience values to backfill (often up to ~24 hours depending on configuration and volume).

Related APIs

Identity Management API (Custom Forms / Custom Fields Management)

• See the Identity Management API documentation section for custom forms.

Last updated: June 26, 2026