Creating and updating custom field keys via API: /publisher/customField

The POST /publisher/customField endpoint creates new custom field keys or updates existing ones for an app. A custom field key is the schema of a custom field — its name, data type, options, validators, and other settings — defining what data the field can hold. The actual data entered by individual users is stored as values, managed by separate endpoints. Pass an array of one or more field keys in the request body.

Request

POST https://api.piano.io/id/api/v1/publisher/customField?aid={{aid}}

Headers

Authorization: {{api_token}}
Content-Type: application/json

Request body

The request body is a JSON array. Each element describes one custom field with the following properties:

Field	Type	Required	Description
`field_name`	string	Yes	Internal identifier of the field. Must match the pattern `[A-Za-z0-9-_]+` (letters, digits, hyphens, underscores), be 100 characters or fewer, and be unique within the app.
`title`	string	Yes	Human-readable label shown in the dashboard and on user-facing forms.
`data_type`	string	Yes	One of: `TEXT`, `NUMBER`, `BOOLEAN`, `ISO_DATE`, `PHONE_NUMBER`, `SINGLE_SELECT_LIST`, `MULTI_SELECT_LIST`.
`comment`	string	No	Internal description for administrators.
`editable`	boolean	No	Whether end users can edit the field’s value. Defaults to `false`.
`required_by_default`	boolean	No	Whether the field is marked as required by default in forms. Defaults to `false`.
`validators`	array of objects	No	Validation rules applied to user input later (not to the create/update request itself). Each entry has three keys: `type` — which validator to use; `params` — its configuration (varies by type); `errorMessage` — the message shown to the end user when their input fails this rule. Supported `type` values: `MIN`, `MAX`, `REGEXP`, `MIN_AGE`, `STR_LENGTH`, `DATE_AFTER`, `DATE_BEFORE`, `ONE_OF`, `MULTIPLE_OF`, `EMAIL`, `WHITELIST`, `BLACKLIST`, `MIN_CHOSEN`, `MAX_CHOSEN`, `PHONE_NUMBER`, `STEP`. Use `[]` for no validation. The request itself is rejected only if a validator’s `params` are invalid for its `type`.
`options`	array of strings	Conditional	Selectable values for `SINGLE_SELECT_LIST` and `MULTI_SELECT_LIST` fields. Required when `options_link` is `0`. Use `[]` when `options_link` is 1–8 (predefined thesaurus) or for non-list field types.
`options_link`	integer	Conditional	For list-type fields, selects either a custom or predefined value list. `0` (or omitted) means custom list — provide values via `options`. `1`–`8` reference predefined thesauruses; in that case `options` can be `[]`. See Predefined values for options_link .
`favourite_options`	array of strings	No	For list-type fields, a subset of `options` to be displayed prominently. Stored alongside the field; rendering depends on the consumer.
`set_name`	string	No	Name of an existing custom field set this field belongs to. The set must already exist; the API does not create sets.
`attribute`	object	No	Type-specific settings. See Attribute object below.
`tooltip`	object	No	Tooltip shown next to the field. Schema: `{ "enabled": boolean, "type": "InfoIcon" \| "HoverOverField", "text": string }`.

Attribute object

The optional attribute object holds type-specific settings. All keys are optional.

Field	Type	Description
`default_value`	string	Pre-filled value for new users.
`placeholder`	string	Placeholder text shown in the input.
`multiline`	boolean	For `TEXT` fields, render as a multi-line textarea.
`date_format`	string	For `ISO_DATE` fields, the display/parse format (for example, `yyyy-MM-dd`).
`autofill`	boolean	Enable browser autofill on this field.
`autofill_type`	string	Browser autofill hint. One of: `off`, `on`, `given-name`, `family-name`, `name`, `email`, `username`, `organization`, `street-address`, `address-line1`, `address-line2`, `postal-code`, `city`, `region`, `country`, `tel`, `tel-national`, `tel-country-code`.
`pre_select_country_by_ip`	boolean	For country fields, preselect a value by IP geolocation.
`dmp_segmentation_enable`	boolean	Enable DMP segmentation for this field.
`global`	boolean	Mark as a global custom field (shared across multiple apps).
`aid_list`	array of strings	App IDs this global field applies to.

Examples

The base call is the same for every variant; only the JSON request body changes:

curl --location 'https://api.piano.io/id/api/v1/publisher/customField?aid={{aid}}'
  --header 'Authorization: {{api_token}}'
  --header 'Content-Type: application/json'
  --data-raw '{{request body}}'

Plain text field with a default value

[
  {
    "field_name": "TESTAPI",
    "title": "TESTAPI",
    "data_type": "TEXT",
    "editable": true,
    "required_by_default": false,
    "validators": [],
    "options": [],
    "attribute": { "default_value": "123" }
  }
]

Single-select list with a custom value list

[
  {
    "field_name": "favorite_day",
    "title": "Favorite day",
    "data_type": "SINGLE_SELECT_LIST",
    "editable": false,
    "validators": [],
    "options": ["Monday", "Tuesday", "Wednesday"],
    "options_link": 0
  }
]

Multi-select list with a custom value list

[
  {
    "field_name": "custom_days",
    "title": "Days",
    "data_type": "MULTI_SELECT_LIST",
    "editable": false,
    "validators": [],
    "options": ["Monday", "Tuesday", "Wednesday"],
    "options_link": 0
  }
]

Single-select list using a predefined thesaurus (here, Countries — options_link: 1)

[
  {
    "field_name": "country_of_residence",
    "title": "Country",
    "data_type": "SINGLE_SELECT_LIST",
    "editable": false,
    "validators": [],
    "options": [],
    "options_link": 1
  }
]

For the full list of options_link values and the values returned by each predefined thesaurus, see Predefined values for options_link.

Last updated: July 03, 2026