Importing Custom Fields

Custom fields allow publishers to store additional information about users, such as birthday, gender, preferences, or country. These fields must be configured correctly and imported via a .csv file to ensure proper syncing with Piano's backend.

Note: This import process is exclusively performed by a Piano representative to bulk import custom fields during the initial Piano launch. For updating users' custom fields at any other time, please use the API as outlined here.

This guide walks you through preparing, formatting, and importing custom fields into Identity Management, including specific rules for field types, formatting requirements, and guidance for using predefined value lists such as Countries, U.S. states, Date formats, Occupation status, Gender, Education level, or Children count.

Step 1: Prepare the Custom Fields in Piano Dashboard

Before importing any data, you must first create all custom fields in the Piano Publisher Dashboard:

• Navigate to: Publisher Dashboard → Manage → Custom Fields

• Create each field you want to import (e.g., gender, birthday, newsletters, etc.)

• Take note of the Field ID of each, as this will be used as the column header in the import file

Step 2: Prepare the CSV File

File Naming

• The filename must be in the format: AID_custom_fields.csv
  Example: uTIyZr2su_custom_fields.csv

File Format

• Must be CSV (comma-separated values)

• Must be UTF-8 encoded

Required Columns

• The first column must be: user_id

• Then follow with the exact field ID(s) you plan to import (e.g., birthday, gender, etc.)

• Only include the custom fields you want to import. For example, if importing custom fields with the IDs birthday and gender, the file should contain exactly three columns: user_id, birthday, gender

Step 3: Formatting Field Values

If a field value contains a comma, enclose it in double quotes. Example: "4389, Ridge Road"

If double quotes are used inside the value, escape them by doubling. Example: Jeromy """"JR""""

Single-Select List Field – Important Notes

If you're using a single-select list custom field with a predefined list of Countries, U.S. states, Date formats, Occupation status, Gender, Education level, Children count, or Accommodation type, you must:

1. Use the exact value provided by Piano. The values must match Piano's list. For example, country names may differ from those used in subscription address fields or other systems. See the complete list of accepted values below.

2. Format the value correctly for import. Example for Colombia: "[""Colombia""]"

Countries

• Antilles

• Antigua and Barbuda

• Angola

• Afghanistan

• Armenia

• Antarctica

• Albania

• Argentina

• Austria

• American Samoa

• Canada

• Burkina Faso

• Switzerland

• Åland Islands

• France

• Aruba

• Azerbaijan

• Bahrain

• Bosnia and Herzegovina

• Australia

• Barbados

• Belgium

• Bulgaria

• Burundi

• Benin

• Brunei Darussalam

• Bermuda

• Bolivia, Plurinational State of

• Bonaire, Sint Eustatius and Saba

• Brazil

• Germany

• Saint Barthélemy

• Bahamas

• Botswana

• Bouvet Island

• Belarus

• Belize

• Cocos (Keeling) Islands

• Congo, the Democratic Republic of the

• Congo

• Central African Republic

• Cabo Verde

• Colombia

• Cameroon

• Czech Republic

• Costa Rica

• China

• Christmas Island

• Cyprus

• Côte d'Ivoire

• Cuba

• Cook Islands

• Serbia and Montenegro

• Curaçao

• Denmark

• Djibouti

• Dominican Republic

• Algeria

• Ethiopia

• Chile

• Faroe Islands

• Ecuador

• Dominica

• Bangladesh

• Egypt

• Micronesia, Federated States of

• Spain

• Falkland Islands (Malvinas)

• Finland

• Estonia

• Gabon

• Bhutan

• Western Sahara

• Fiji

• Eritrea

• Andorra

• United Kingdom

• Grenada

• Georgia

• French Guiana

• Guernsey

• Ghana

• Gibraltar

• Greenland

• Gambia

• Guinea

• Guadeloupe

• Equatorial Guinea

• Greece

• South Georgia and the South Sandwich Islands

• Guatemala

• Guam

• Guinea-Bissau

• Guyana

• Hong Kong

• Heard Island and McDonald Islands

• Honduras

• Croatia

• Haiti

• Hungary

• Indonesia

• Ireland

• Israel

• Isle of Man

• India

• British Indian Ocean Territory

• Iraq

• Iran, Islamic Republic of

• Iceland

• Italy

• Jersey

• Jamaica

• Jordan

• Japan

• Kenya

• Kyrgyzstan

• Cambodia

• Kiribati

• Comoros

• Saint Kitts and Nevis

• Korea, Democratic People's Republic of

• Korea, Republic of

• Kuwait

• Cayman Islands

• Kazakhstan

• Lao People's Democratic Republic

• Lebanon

• Saint Lucia

• Liechtenstein

• Sri Lanka

• Liberia

• Lesotho

• Lithuania

• Luxembourg

• Latvia

• Libya

• Morocco

• Monaco

• Moldova, Republic of

• Montenegro

• Saint Martin (French part)

• Madagascar

• Marshall Islands

• Macedonia, the former Yugoslav Republic of

• Mali

• Myanmar

• Mongolia

• Macao

• Northern Mariana Islands

• Martinique

• Mauritania

• Montserrat

• Malta

• Mauritius

• Maldives

• Malawi

• Mexico

• Malaysia

• Mozambique

• Namibia

• New Caledonia

• Niger

• Norfolk Island

• Nigeria

• Nicaragua

• Netherlands

• Norway

• Nepal

• Nauru

• Niue

• New Zealand

• Oman

• Panama

• Peru

• French Polynesia

• Papua New Guinea

• Philippines

• Pakistan

• Poland

• Saint Pierre and Miquelon

• Pitcairn

• Puerto Rico

• Palestine, State of

• Portugal

• Palau

• Paraguay

• Qatar

• Réunion

• Romania

• Serbia

• Russian Federation

• Rwanda

• Saudi Arabia

• Solomon Islands

• Seychelles

• Sudan

• Sweden

• Singapore

• Saint Helena, Ascension and Tristan da Cunha

• Slovenia

• Svalbard and Jan Mayen

• Slovakia

• Sierra Leone

• San Marino

• Senegal

• Somalia

• Suriname

• South Sudan

• Sao Tome and Principe

• El Salvador

• Sint Maarten (Dutch part)

• Syrian Arab Republic

• Swaziland

• Turks and Caicos Islands

• Chad

• French Southern Territories

• Togo

• Thailand

• Tajikistan

• Tokelau

• Timor-Leste

• Turkmenistan

• Tunisia

• Tonga

• Turkey

• Trinidad and Tobago

• Tuvalu

• Taiwan, Province of China

• Tanzania, United Republic of

• Ukraine

• Uganda

• United Arab Emirates

• United States Minor Outlying Islands

• United States

• Uruguay

• Uzbekistan

• Holy See (Vatican City State)

• Saint Vincent and the Grenadines

• Venezuela, Bolivarian Republic of

• Virgin Islands, British

• Virgin Islands, U.S.

• Viet Nam

• Vanuatu

• Wallis and Futuna

• Samoa

• Kosovo

• Yemen

• Mayotte

• South Africa

• Zambia

• Zimbabwe

U.S. States

• Alabama

• Alaska

• Arizona

• Arkansas

• California

• Colorado

• Connecticut

• Delaware

• District Of Columbia

• Federated States Of Micronesia

• Florida

• Georgia

• Guam

• Hawaii

• Idaho

• Illinois

• Indiana

• Iowa

• Kansas

• Kentucky

• Louisiana

• Maine

• Marshall Islands

• Maryland

• Massachusetts

• Michigan

• Minnesota

• Mississippi

• Missouri

• Montana

• Nebraska

• Nevada

• New Hampshire

• New Jersey

• New Mexico

• New York

• North Carolina

• North Dakota

• Northern Mariana Islands

• Ohio

• Oklahoma

• Oregon

• Palau

• Pennsylvania

• Puerto Rico

• Rhode Island

• South Carolina

• South Dakota

• Tennessee

• Texas

• Utah

• Vermont

• Virgin Islands

• Virginia

• Washington

• West Virginia

• Wisconsin

• Wyoming

Date Formats

• mm/dd/yyyy

• mm.dd.yyyy

• dd/mm/yyyy

• dd.mm.yyyy

• yyyy/mm/dd

• yyyy.mm.dd

• yyyy/dd/mm

• yyyy.dd.mm

Occupation status

• Full-time work

• Part-time work

• Full-time parent

• Student

• Unemployed

• Self-employed

• Retired

Gender

• Male

• Female

• Non-binary

• Other

Education level

• Postgraduate degree

• University degree

• High school

• Less than high school

Children count

• 4 or more

• 3

• 2

• 1

• None

Accommodation type

• Rental apartment

• Apartment

• Rental house

• House

• Parents' home

• Other

Step 4: File Size Limits

• Recommended size per custom field: 1KB

• Recommended total size (all fields): 4KB

• Absolute maximum size: 8KB

Step 5: Upload Eligibility

Custom field imports can be used with:

• Identity Management

• Identity Linking

Step 6: Example File

Here's an example of a correctly formatted .csv file.

Headers:

user_id,gender,client_id,birthday,opt_in,country,newsletters

Values:

12345,male,345678,2019-05-16,false,"[""Colombia""]","[""Politics"", ""Local""]"

For more details about the import process please visit this link.

Last updated: June 24, 2026