Custom Fields in Identity Management

Configuring Custom Fields

You can find the configuration screen under Manage → Custom Fields. This will bring up an interface that is split into two main components, a Fields section and a Forms section. The Fields section is on the left, and displays fields available in your application, and on the right are the forms that you have created (the Registration and My Account forms are included by default).

Fields

Within the Fields section of the screen, you can see any fields that you have created, with the number of responses associated with a given field presented to the right, next to the ellipsis menu.

Creating Fields

You can create a custom field by clicking the Add Field button on the left side of the screen. Doing so will cause this modal to appear:

From here, there are a few configurable options that you will need to complete to create this custom field. First, you must specify the type of data you would like to collect with this particular field.

Notice that at the top of the modal, there are two tabs: the default Manage tab and a second tab labeled Validators (the only exception is that Checkbox field types do not have validator options).

Within the Manage tab are general system information fields that define how the field is presented and how it should be referenced in the API.

Largely, the Manage section is the same for each field type, and you will need to specify a Field title and Field ID for each, as well as an optional Description. There is also a checkbox labeled "Allow user to update the field" which, when checked, permits the user to edit the input information after the initial submission of the form.

You can also send fields to Piano Audience as described here.

Note, that for the field to be available in Audience, the Custom Field ID cannot start or end with a number, have a length greater than 23 characters, or contains minuses or underscores.

The Validators tab is populated with some options you have when defining the requirements of the field. Here, you can specify which responses should be considered valid. For example, you can configure a maximum character count for a text response or a minimum value for a number. There is more information on validators below.

Field Types

The field type you select will have an effect on the placeholder, default value, segmentation and validation options that you can then apply to the field. It will also affect the fields within the Validators tab of the modal. The options are

• Text: You can prompt the user with a free-form text box. This is often ideal for collecting text responses that don't fit neatly within or can't be captured by a list of options. Note that capitalization is disregarded when performing operations on text fields. The Mine Users search based on a text custom field is limited to 4000 characters.

• Date: A date field can be used for collecting birthdays or other anniversaries. A default date format can be set to display to users.

• Number: Number fields are also presented as a free-form text box, but all entries must be integers so mathematical comparisons can be applied.

• Checkbox: Checkbox fields can be presented if, for instance, you would like to ask a user if they wish to subscribe to your newsletter. These are not meant to replace Consent Fields, but can be used for consent purposes if you wish to set consents on custom forms.

• Single-select: You can create a set list of options, of which the user can choose one.

• Multi-select: You can create a set list of options, of which the user can choose multiple.

• Scale: Create a range of numbers, and prompt users to enter a number in the range. This is ideal for collecting feedback like customer satisfaction.

Unique Configuration Fields within Manage

As mentioned, the configurable options within the Manage section of field creation are largely the same across all field types. Each field may have a placeholder and default value of the field type. The placeholder will appear to the end user before they begin inputting their response to the field, as an example. The default value will also appear to the end user before they begin input, but if they don't alter it, it will be submitted with the form and attached to their profile.

Text fields will also have the option to select if you'd like to display them as "Single-line" or "Multi-line".

• If the text custom field has the single-line option selected, it displays only one line, and this element is represented as an input

• If the text custom field has a multi-line option it can increase in height depending on the amount of text entered and this element is represented as a textarea

The exceptions are multi-select and single-select field-types, which have an additional configuration field, List options. In this field, you must define the options that you would like to present to the user.

You can select a pre-configured set of options for Countries, U.S. states, Date formats, Occupation status, Gender, Education level, Children count, or Accommodation type.

In the case of the Countries list, you will also have the option to check the following checkbox "Prefill country based on geolocation":

This will pre-populate the country value by GeoIP in the respective custom field within the checkout.

You may create a new list by selecting Custom list and populate it with options that you would like. If you opt to create a new option list, you will see the following screen upon clicking the Add field button.

Here you need to populate the list with options of your choice, with no limit to the number or content of options provided. Options in a list can be uploaded in a .csv file instead of manual entry. The file size for the upload must be less than or equal to 10MB. You can also set an option to be the default option, where it will be the first available option that the user sees on the list.

Please note that in case you are passing the field values of a single-select or multi-select list type custom field via API or as part of a JWT payload, said value needs to be present as an item of your custom list.

Unique Configuration Fields within Validators

More notably, most of the differences between field types lie within the Validators tab of the modal. With each validator option, you can configure the error message presented to the end user to your preference.

Text Fields

• Admit by regexp: If you are familiar with the syntax of regexp, this option can be extremely useful for defining the constraints of your field. You may specify the type of characters you would like to support as well as any particular format that is required.

• Email: Checking this box ensures that the content entered by the user is in the form of an email address, meaning it contains an "@" symbol and ends in a top-level domain name.

• Length: Here you can specify the minimum and maximum length you would like from user responses. Any user with a response outside of this range will be shown the error message you configure.

• Whitelist: You can also enter certain options that the user's text must match. If the user's value does not match any of the input options, they will be shown the appropriate error message. Any input that contains the whitelisted values will be accepted. All others will be rejected.

• Blacklist: The opposite of Whitelist, this is where you can configure options you explicitly do not want to be submitted.

Date Fields

• Minimal age: You can specify the minimum amount of time that has passed since the input date to grant access.

• Date after*: Here you can specify a set date and only allow users to proceed if their input date falls on or after that date.

• Date before*: Similarly, you can specify a date and only allow users whose input date falls on or before that date.

• *Current date: You can optionally use this checkbox for either Date before or Date after to disable the date picker and select the current date.

Number Fields

• Minimum value: You may set a minimum value for numbers and only admit users who have input a higher number.

• Maximum value: Conversely, you can set a maximum value for numbers.

Checkbox Fields

There are no validator options for checkboxes.

Checkbox field titles (the labels displayed next to checkboxes) support HTML markup, allowing you to include formatted text and clickable links in your checkbox labels.

Common Use Cases:

• Adding links to privacy policies or terms of service

• Including formatted text with emphasis or styling

• Creating interactive consent checkboxes with embedded documentation links

Example:

I agree to the <a href="https://example.com/privacy" target="_blank">Privacy Policy</a>

Security:

All HTML content in checkbox field labels is automatically sanitized to prevent security vulnerabilities:

• Dangerous tags (such as <script>) and event handlers are automatically removed

• Links with target="_blank" automatically receive rel="noopener" for security

• Only safe HTML tags and attributes are allowed

This HTML rendering applies to:

• End-user registration and login forms

• User profile views in the publisher dashboard

• All templates where checkbox custom fields are displayed

Single-Select Fields

• Must be one of: You can input options that the user's value must match. You can input as many options as you would like, and if the user's response does not match a single option, the user receives an error.

Multi-Select Fields

• Min chosen: Here, you should specify the minimum number of options you require from the user.

• Max chosen: Likewise, you can set a limit to the number of options a user may select.

• Must be all of: You can input options that ALL of the user's input values must match. For example, if you input "Option 1" and "Option 2," users who input "Option 1" only will NOT be admitted. However, users who input "Option 1," "Option 2," and "Option 3" WILL be admitted.

Field Sets

You may also add a field set which is a group of fields that are in some way associated. Piano provides three pre-configured field sets, Billing address, Shipping address, and Default fields. But you can create your own by clicking on ADD FIELD SET.

Once you have created a fieldset, those fields can be simultaneously placed within a form, and they will be positioned together within that form.

Editing Fields and Field Sets

You can edit any existing field by clicking the ellipsis icon (three dots) next to that field. Once a field has been created, you can no longer change the field type or the field ID because these are system fields that are intrinsically linked with the field. However, you can edit the field title and description as well as all validators at any time.

You may also edit field sets after creating them by adding or subtracting fields from the set, though similarly, you cannot change the ID of the field set after it has been created.

Deleting Fields and Field Sets

When you click on the X icon next to a given field, you will be presented with several options. You will have the option to remove the field from all forms (if it is currently in a form). Clicking this option will not remove it from your list of fields.

You also have the option to delete a field, though a field can only be deleted if it does not have associated user data. Otherwise, the only option is to archive the field, meaning the field will be deactivated but otherwise remains present in the field list.

Clicking the X icon next to a field set will also present two options. You can either delete the set without deleting the fields, or you may delete both. Deleting only the set will ungroup the fields, but otherwise, the configuration remains the same. Deleting both the set and the contained fields will remove the set, but will also either archive or delete the associated fields (depending on their collected data).

Phone Number Field Sets

Phone number fields can be added as a field set under Manage → Custom Fields → Default Fields and Sets → Phone Number.

The "Edit" field modal window can be accessed in the Custom Fields manager by clicking on the ellipsis menu next to the field:

Alternatively, you can edit the phone number field in each custom form to which it's been added. For example, here you can see how it can be edited if included in the "Registration form", and also via the ellipsis menu:

Manage

This tab allows you to set a Field title and Field description for the phone custom field. Further down, you can then adjust some display settings, including placeholders, default values, or tooltips.

Validators

The error message for the phone number area code validator can be set in the "Validators" tab.

Configure the Blacklist and Whitelist in the "Format" tab.

Kindly be aware that only specific countries may have a list of area codes for phone numbers available (e.g., Canada, Dominican Republic).

To configure a Blacklist for a selected country, you need to select the area codes of telephone numbers from the drop-down list:

And then check the "blacklist" option:

Similarly, to configure a Whitelist, you need to select the area codes from the list and the respective option for whitelisting.

If a user tries to save a phone number with an area code from the blacklist, they will receive a validation error specified in the "Validators" tab.

If the text of the validation error is not specified in the "Validators" tab, the default one is set to "Phone number: Area code of a phone number is not from whitelist/blacklist."

If the phone number has an invalid format that does not match any existing format, the following validation error will be displayed: "Phone number: Phone number is not valid"

Format

The default area code can exclusively be configured within the "Format" tab. In all other dropdown menus, both within the publisher dashboard and on the end-user page, only the designated list of area codes is visible.

This specified list of area codes for a phone number is presented not only in the "Edit field" modal window but also in the "Edit field conditions" modal window for each form where the phone number field is included. Consequently, altering the default area code based on the default phone number may not be the optimal solution, as it can vary for each distinct form. It's essential to note that the default value set in the "Manage" tab does not necessarily have to match the default area code established in the "Format" tab.

Here is an example of how the Register page template will look like with phone number formats of multiple countries added:

And here is an example of how it will look if only one country's phone number format is added:

Default fields

For more information about Default fields, please head to this article.

Forms

Fields themselves will never be presented to users unless they are displayed within forms.

By default, there are two forms built into Identity Management – the My Account form and the Registration form.

Default Forms

Piano provides two undeletable and unarchivable forms you can start with.

The My Account form is displayed first in your list of forms. Users will only see this form in the Profile component of the My Account widget; it is not possible to trigger this form any other way. The fields contained in this form are displayed to all users (unless you have conditions configured on the form), so keep this in mind as you are deciding which fields to keep in the form. When you create a new field, it will automatically be added to this form – be certain to remove it if you do not want it to be presented to users.

The Registration form is, in general, treated the same as any form that you create. The primary difference is that the Registration form is the form that is displayed when you call tp.pianoId.show() without any parameters.

Multi-Step Forms

It can be easier to split many, related questions for end users across different steps within a single form. This introduces form-level conditions, where subsequent steps may be dependent on the user's answers to the previous questions. Explore configuring and using multi-step forms.

Creating Forms

If you would like to create a new form to show to users, simply click the Add form at the top right of your interface. This will bring up a modal asking you to provide a form title and ID.

Set a title and an ID for your form. The title may be shown to end users using the formTitle directive in a Piano ID custom form template, while the ID is used for Piano API and JavaScript calls.

More details about the Multi-steps setting are available here.

Once you have populated these inputs, you can click Add to create the form. It will then appear in your list of forms, alphabetically by form ID.

The My Account Form is always listed first.

Adding Fields to Forms

You may also drag and drop a field from the left side of the screen into one of the forms. The order in which you position the fields in the form is the same order in that the user will see them when they attempt to register or edit their information.

You may also drag and drop a field set to a form, and the entire set will be added to the form.

Editing Forms

Clicking the pencil icon inline with the form titles will present you with the following modal:

Here you can edit the form title. You cannot edit the ID of a form after it has been created.

More details about the Multi-steps setting are available here.

Clearing Fields from Forms

There is a trash bin icon inline with the form names at the far right of the screen. Clicking that icon will present a confirmation modal asking you if you would like to archive, delete, or clear the form. Click the Clear form button in the bottom left of the modal to remove the fields from the form. This does not delete or archive the form, it simply empties the form.

If you wish to remove individual fields from a form, you can do so by clicking the X icon inline with the appropriate field, also on the right. Doing so will not delete the field but will instead only remove it from the form.

Deleting and Archiving Forms

You can choose to delete or archive forms by repeating the above process of clicking on the trash icon associated with each form. In the resultant modal, click the Archive button or click on the arrow and select the appropriate option to delete the form.

To unarchive a form that you have previously archived, click the gear icon next to the form and confirm the action.

Form Conditions

Near the right side of each field in a form, there is a three-dot menu. Clicking this menu reveals options to Edit or Delete the field. Choosing Edit opens a modal with three tabs – Conditions, Validators and Display – with Conditions as the default open tab.

Within this modal, you will see a checkbox labeled "This field is required", as well as an option labeled "Add condition."

Marking the checkbox will not permit the user to submit the form without completing the given field.

To only show required fields, wrap them in the <required-custom-fields> </required-custom-fields> tag. These tags can be adjusted on the Identity Management Confirm Registration template in the Template Manager.

You may also add a condition to the field, with options being Appear, Prefill, and Prefill content. Note that Prefill content is only an option if you have an identical field type somewhere else in the form. These options allow you to link the given field to the contents of another field in the form. You may add multiple conditions to a single field.

Appear: In this case, the field will only appear if a certain condition is met with respect to another field. For example, this can be useful for presenting a single-select list of U.S. if the user selected "United States" for their country field.

Prefill: With prefill, you can set the contents of the field to a specific value if the specified condition is met. This value is not dynamic, so you need to input the desired value.

Prefill content: Prefill content automatically fills the given field with the data of another field if a certain condition is met. This value is dynamic, so it will respond to user input rather than requiring that you specify a value.

You may click on the X icon next to each condition to discard that condition. You may also click the + Add condition button near the bottom of the modal to add further conditions.

Form Validators

You may apply validators on the form level that can be different than the validators applied to the field itself. Click on the three-dot menu next to a field within a form, select Edit and navigate to the Validators tab. Upon doing so, the first object you will see is a toggle labeled "Override default field validation."

Toggling this switch will enable you to configure new validators for the field. The options for these validators are the same as those described above.

Any new validators you apply at the form level will not affect the field validators that you previously created, nor will it affect the validators applied to the field in other forms. Any validator applied at the field level will still apply unless it conflicts with the validators applied at the form level.

Form Display

Additional options are available for you to apply different display configurations on the form level that can be different from what was set on the field level. Click on the three-dot menu next to a field within a form and navigate to the Display tab.

• Date

  You can configure several display settings for date fields, including Placeholder, Default value, and Format.

  • Placeholder – Defines the helper text shown inside the field before a user enters a value. This text indicates the expected input format or example date.

  • Default value – Specifies a date that will automatically appear in the field when the form loads. Users can keep or modify this value.

  • Format – Determines how the date is displayed to users (for example, dd/mm/yyyy or mm/dd/yyyy). The default date format can be customized and displayed differently across various forms such as Registration, My Account, and Custom forms.

  If you change the date format at the form level, it will override the default format defined on the field level. This change applies only to the specific form where the modification is made.

  The US date format (mm/dd/yyyy) will still be displayed in the User Profile under the Custom Fields tab and in the Manage custom field modal. The configured date format also does not affect dates displayed in emails sent to users.

  

• Text

  You can configure several display settings for text fields, including Placeholder, Default value, and Web browser auto-fill.

  • Placeholder – Defines the helper text displayed inside the field before the user enters any information. This text can provide guidance or an example of the expected input.

  • Default value – Specifies a value that will automatically appear in the field when the form loads. Users can keep this value or modify it.

  • Web browser auto-fill – Enables the user's web browser to detect the text field and automatically fill it with stored information.

    • Off – Disables browser auto-fill for this field.

    • Based on field ID – The browser attempts to detect and auto-fill the field based on the field's ID.

    • Others – Uses standard browser auto-fill field types. Available options include: First name, Family name, Name, Email, Username, Organization, Street address, Address line 1 & 2, Postal code, City, Region, Country, Phone, National phone number and Country code.

      

Form Behavior

The Identity Management form behavior is a crucial aspect of providing a seamless and personalized experience for users during the registration, but also checkout process.

The Show Offer card is designed with two tabs, the first being the Offer tab. This tab empowers clients to select the specific offer they wish to present to users during the checkout process.

For clients utilizing Custom fields, there is a unique capability to associate specific forms with each term in the offer. Consequently, users navigating through the checkout flow encounter the relevant form based on the term they select during checkout.

When it comes to unregistered users, there are two distinct options for displaying custom fields associated with a form:

1. Display Custom Fields from Custom (Checkout) Form in Registration Form:

   • Custom fields from the custom (checkout) form replace Custom fields from the registration form.

   • The custom (checkout) form does not appear separately after the user registers.

2. Don't Display Custom Fields from Custom (Checkout) Form in Registration Form:

   • Custom fields from the custom (checkout) form are excluded from the registration form.

   • The custom form is displayed separately after the user registers.

Note, that the first option of the form display (i.e. "Show custom fields from checkout in registration form") is enabled by default on any new or existing applications. If you'd like to have the second option configured on your application, please get in touch with Piano Support at support@piano.io.

This configuration also extends to the social login process.

The setting "Checkout authentication in separate state" from the Edit Business section also plays a pivotal role.

When disabled, custom fields from the custom (checkout) form will ALWAYS be visible in the registration form, as there will be no separate display of the checkout modal. More details about this setting are available here.

It's important to note that these configurations significantly impact the user experience during registration and checkout, and careful consideration should be given based on the desired flow and customization requirements.

For more detailed guidance on configuring form behavior we've compiled the below overview table.

Below you can find a mockup of how the registration and custom (checkout) forms may look like based on the settings defined for the case of "Scenario 3".

Registration form

Checkout form

Custom Fields Tooltip

Custom fields tooltip allows clients to enhance custom fields by including a 240-character tooltip message. The tooltip can be used to inform end-users, explain the field's purpose, and enhance user experience.

Configuring Tooltip

The tooltip can only be configured at the field level. This means the customization happens at the custom field's point of creation, or when editing an existing custom field. You may want to configure the tooltip by selecting Manage → Custom fields → Add field or selecting the ellipsis (three dots) to edit the field.

Displaying Tooltip

Selecting Add field will open the creation modal. You will notice a Display section available to edit. The Display section and its tooltip options are available for all custom field types. There are two types of tooltips available to select: Information icon and Mouse hovers over field.

1. Information icon: Display an information icon to the right of the label in My Account and the User Profile. On the login/registration modal, the information icon will be available on the right side of the custom field. Clicking on the information icon will display the tooltip.

2. Mouse hovers over field: Display the tooltip only when the mouse hovers over the field label for at least two seconds. This option is helpful if you want a clean visual experience but still want to display information.

Once you have selected the tooltip type, enter the custom field tooltip in the text box. There is a 250 character limitation for the tooltip text to prevent unusually long texts. Note that as a default, the option None will be selected.

Mine Users

Please visit this link for more information about how to Mine Users by Custom fields.

Custom Fields in Composer

The Custom field segmentation options in Composer are detailed here.

Show Form card

Read more about the Show Form card here.

Show Offer card

Read more about how to select term-specific forms here.

User Experience

Much of the functionality surrounding Custom Fields relies on the user experience. For example, the user must be aware when the form has rejected a response they submitted because of a validator.

Registration

On registration, the user will see the fields that you have included in the registration form. The default template provided by Piano will result in a registration form with custom fields that resembles the following:

Adjusting Templates and Style

Custom fields do not show in the registration form: If you are experiencing this issue, it is because the registration template did not update in order to avoid conflicts. Navigate to Manage→Templates→Identity Management→Piano ID register page. In this case, it is a simple matter of inserting <custom-fields></custom-fields> at the appropriate line of this template. We recommend inserting custom fields following the input groups for name, email, and password. You can click the Compare with default button at the top right of the screen to better understand where to include this code.

Show custom fields in a different order: Piano also allows you to render a custom field separately from the custom fields group in cases where Prefixes or Titles are needed when users enter their names. To do this, you will need to insert <custom-field fieldName="fieldName"></custom-field> snippet into the appropriate line with the field's name in this template. This snippet can be used in any custom forms as well.

Custom fields are not styled correctly: If your custom fields do not exhibit proper styling, it is because the registration layout template did not update in order to avoid conflicts. Navigate to Manage→Templates→Identity Management→Piano ID layout. Here, there are numerous lines of code that pertain to the styling of custom fields. We strongly suggest you click Compare with default to get a sense of where your template diverges from the system default and copy the appropriate code into your own template.

Show form template needs to be changed: To change the text or behavior of the modal that appears to users when they trigger the Show form card, navigate to the Piano ID custom form template.

If you are still having difficulty with the display of your custom fields, please reach out to a Piano representative, and we will be glad to assist you.

Errors

When a user submits information that does not satisfy the validators that you applied to the fields within the form, they will receive the error messages that you defined. The error display will follow this format [Field name]: [Error message]. Multiple error messages will be displayed at once if there is more than one instance of invalid data.

Social registration

Non-required custom fields can be shown after social registration, such as when an end user creates an account through Google, Facebook, or other social providers. Required fields will always be shown after social registration, but non-required fields may be shown or hidden with a checkbox in the Identity Management main modal:

My Account

When the user navigates to the "Profile" tab of My Account, they will see the fields that you have included within the My Account form. This might include more or fewer fields than you configured for the registration form. It will also include fields that you may have added to the registration form and My Account form since the user first registered.

Here, the user will be able to view their responses and edit the fields that you configured to be editable. Any fields that the user did not complete upon registration appear as blank. All users see the same My Account form, regardless of the time or circumstances of their registration.

Again, the user will receive error messages if they attempt to submit information that does not match the validators that you have defined for your fields.

Show custom fields in a different order

You can show custom fields in a different order on your MyAccount page similar to the registration and custom forms. To do this, please insert the following snippet in the appropriate line:

// single custom-field
  <div class="tp-form form-horizontal">
    <custom-field fieldName="fieldName">
      <ng-template let-field>
        <div class="control-group">
          <label class="control-label" customFieldLabel [fieldName]="field.field_name"></label>
          <div class="controls">
            <custom-field-input [fieldName]="field.field_name"></custom-field-input>
          </div>
        </div>
      </ng-template>
    </custom-field>
  </div>

// for rest custom fields
  <custom-fields class="tp-form form-horizontal">
    <ng-template let-field>
      <div class="control-group">
        <label class="control-label" customFieldLabel [fieldName]="field.field_name"></label>
        <div class="controls">
          <custom-field-input [fieldName]="field.field_name"></custom-field-input>
        </div>
      </div>
    </ng-template>
  </custom-fields>

Please be aware, that if you choose to render a custom field separately from the rest of the Custom fields group using the method outlined above, you can no longer use Custom field conditions that are dependent on the Custom field that you are rendering separately.

When viewing a user's custom fields in the Piano Dashboard under Users → All users → [user] → Custom fields (tab), you can control how the fields are displayed using the view mode selector in the toolbar.

Sort Options:

• Last Updated (default) - Sorts custom fields by their last update timestamp, with the most recently updated fields appearing first. Fields without an update timestamp appear at the bottom.

• Field Name A-Z - Sorts custom fields alphabetically by their title in ascending order (case-insensitive).

The selected sort mode is saved in your browser's local storage per application ID and will persist across sessions.

Search Functionality:

A search bar is available in the toolbar to filter the custom fields list. You can search by field title (display name) or field name (internal field ID). The search is case-insensitive and filters results in real-time as you type.

APIs

Search custom fields via API

In order to search by custom fields via API, you should use specific conditions for each type. Here is a mapping between condition type and custom field type:

Condition type: LIKE
Operators: like
Custom Field Type: TEXT

Condition type: EQUAL,
Operators: equal, optionsEqual for SINGLE_SELECT_LIST
Custom Field Type: TEXT, NUMBER, BOOLEAN, SINGLE_SELECT_LIST, ISO_DATE

Condition type: MORE,
Operators: more
Custom Field Type: ISO_DATE, NUMBER

Condition type: LESS,
Operators: less
Custom Field Type: ISO_DATE, NUMBER

Condition type: BETWEEN,
Operators: more, less
Custom Field Type: NUMBER, ISO_DATE

Condition type: IN,
Operators: optionsIn
Custom Field Type: MULTI_SELECT_LIST

Condition type: 'EMPTY',
Custom Field Type: TEXT, NUMBER, ISO_DATE, SINGLE_SELECT_LIST, MULTI_SELECT_LIST

Condition type: 'ANY',
Custom Field Type: TEXT, NUMBER, BOOLEAN, ISO_DATE, SINGLE_SELECT_LIST, MULTI_SELECT_LIST

For example, to search users by custom field birthdate which has ISO_DATE type with condition between. ISO_DATE supports this condition type, and BETWEEN requires two operators: more and less, so your request should be:

[
{
"field_name":"birthdate",
"data_type":"ISO_DATE",
"condition":{
"type":"BETWEEN",
"more":"1980-02-02",
"less":"2011-02-01"
},
"response_time":{
"type":"CURRENT"
}
}
]

More information on how to search for users who updated their custom fields during any date range via API is available here.

Please note, that it might take a few seconds for the new custom field values to appear in the Piano dashboard's UI (up to one minute on Sandbox).

Another way to build a request is the network tab in Chrome Dev Tools. Open Dev Tools → network tab, then open User Mining → Search by Custom Fields → specify all required params → Search. In the Network tab select XHR, then select last search request. Open the Headers tab, scroll down to Request Payload and find customFields item. There will be a request with extra fields which is fully compatible with the request described above. You can simply delete fields that are not described in this doc.

Last updated: June 24, 2026