Best practices for form design


This document specifies best practices for form designers/developers to insure correct interoperability with Fill It by Personal.

The Fill It application is implemented in two parts:

  • Bookmarklet that is inserted into a 3rd party page 
  • Fill It application hosted by Personal

To ensure correct interoperability, follow these general guidelines:

  • Use 'p3name'  - this requires developers have access to the form. This will ensure good Fill It performance. See below for information on how to use 'p3name' attributes.
  • Map the form fields using 'Fill It' (can be done by standard users) - See 'Form mapping using Fill It' below.
  • Report problem to Personal by "report a problem" link and specifying the form to check. Personal administrator will check the form and map and adjust the mappings if needed.

Fill It Basics

When FIll It is launched, the bookmarklet is loaded into the 3rd party page. The bookmarklet detects all the forms on the page and sends them to Personal.

On the backend, mapping process between form fields and Personal fields is performed for each of the form fields.

Fields are mapped based on the following information:

  • 'p3name' property if available. If this is available, Fill It will ignore all other info.  
  • Field 'name'
  • Field 'label'

The matching process has a few steps:

  • Each form field is examined for presence of "p3name" attribute as well as field 'name' and corresponding field label. 
  • Explicit Mapping:  If 'p3name' attribute is specified, it will set the mapping.  This mapping will guarantee that your form is matched accurately to the Personal fields. This is the preferred method of mapping.
  • Statistical Mapping:  If 'p3name' attribute is NOT specified, the application will recommend mappings based on previous statistics, both global and for this particular form
  • Name Mapping: If there are no statistics for this field (form field is visited first time), a name search will be performed and the best result based on name match will be suggested
  • Finally, if there is no close name match, this field will be flagged as not-supported.  Future users can update the mapping manually to meet their needs. These fields are not shown in “simple” mode. 

Best Practices for Form HTML structure and elements

These guidelines define how HTML forms and elements should be structured in order to detect correct mapping.

Good Form Development Practices

As a rule of thumb. the simpler the form structure, the better the interoperability. 

Simple form (using 'p3name)

    <label for="firstname">First name</label>

    <input p3name="firstName" id="firstname" type="text" name="firstname"/><br/>

In this case, mapping is explicitly set to 'firstName'. No statistical or name matching will be performed.

SImple form (using labels):

    <label for="firstname">First name</label>

    <input id="firstname" type="text" name="firstname"/><br/>

In this case, statistical mapping will be attempted on field name ("firstname"). If not present, name search will be performed on label ("First name"). 

Poor Form Development Practices

Badly defined form (no labels)

First name

<input id="firstname" type="text" name="firstname"/><br/>

In this case "First name" is just text, not a label. Fill it cannot make a correlation between the input field and corresponding label. Statistical mapping will still work fine, but the first users to visit the form will likely need to change the mappings manually (which will be difficult for non-advanced users). This will also be true for cases when you define labels using some other methods (images, CSS, etc.). 


It is recommended NOT to use HTML 'fieldset' when designing forms.

Hidden fields

Fill It skips all the hidden fields on the form. If hidden fields are used for data submission, Fill It will not be able to populate them.

Javascript and data mangling

If the form uses javascript for data handling, moving it to hidden fields or some other data manipulation, Fill It may not be able to correctly fill the form.

[Do we want to comment on using Flex here or any other formats not covered?]

Using Fill It with fully validated personal fields

Some of the fields in Personal are marked as 'fully validated'. This applies to finite enumerations such as gender (Male/Female), state (50 state list), countries (country list), etc. When designing forms with fields that map to one of these fully-validated fields, form designers should review the list of available values and appropriate formats. If possible, form designers should use field values provided by Personal. Personal uses standard enumeration types and works hard to keep them up-to-date. If there is a problem with missing values, please send us feedback, and we will try to address the problem.

Field formats

Some personal fields are supported in multiple formats. When searching through the list of fields, format identifiers are shown in {<format id>}. When mapping to form fields, only compatible formats are shown.

For example, 'state' field can be specified in long or short format. When defining forms, both of the form specifications will work.

Long 'state' format.

<label for="state">State (long)</label><br/>

<select name="state" id="state">

    <option value="alabama">Alabama</option>

    <option value="alaska">Alaska</option>


Short 'state (abb)'

<label for="state1">State Short</label><br/>

<select name="state1" id="state_short">

    <option value="al">AL</option>

    <option value="il">IL</option>


Form mapping using 'Fill It' application

The Fill It application supports changing field mappings as one of its standard features.

Field mappings can be changed by clicking on the field name to the left of the field and searching and selecting the appropriate Personal field name. It is easy to see which field on the form matches to the field in Fill It because of the green highlight on the form field. Different mapping options also list the compatible field formats (see below in 'formats' section) Once the new mappings are selected and form is submitted, the new mappings are included in mappings statistics and the most popular mapping will be displayed to future visitors to your form.


If there is not a match for your form field in Personal, the field can also be marked as "not supported".

In 'simple' mode (default), all the 'not supported' fields are hidden. This simplifies the user experience for non-advanced users. Clicking on 'advanced' shows all the fields including 'not supported' ones.

Pubished value for 'p3name' attribute and formats

Published field names Current gem mappings: template id (template name) Current field mappings: Internal field name (field display)
title  0000 (Name) name_title (Title) -
firstName  0000 (Name) preferred_first_name (First Name) -
middleName  0000 (Name) preferred_middle_name (Middle Name) -
middleName{initial}  0000 (Name) (Middle Initial)
lastName  0000 (Name) preferred_last_name (Last Name) -  0000 (Name) (Full Name)
contactType  0001 (Contact Info) contact_info_type (Contact Info Type) -
email  0001 (Contact Info) personal_email (Primary Email) -
secondaryEmail  0001 (Contact Info) personal_secondary_email (Secondary Email) -
mobileTelephone  0001 (Contact Info) home_mobile_phone (Mobile Phone) -
telephone  0001 (Contact Info) home_phone (Phone) -
faxNumber  0001 (Contact Info) contact_info_fax (Fax) -
url  0001 (Contact Info) personal_website (Website) -
facebookProfile  0001 (Contact Info) facebook_profile (Facebook Profile) -
twitterUsername  0001 (Contact Info) twitter_name (Twitter Username) -
carProductID  0008 (Car) car_vin (VIN) -
carYear  0008 (Car) year (Year) -
carManufacturer  0008 (Car) make (Make) -
carModel  0008 (Car) model (Model) -
driversLicNumber  0012 (Driver's License) drivers_license_number (Driver's License Number) -
driversLicState  0012 (Driver's License) state_issued_drivers_license (Driver's License State) -
driversLicStartDate  0012 (Driver's License) drivers_license_issue_date (Driver's License Issue Date) -
driversLicEndDate  0012 (Driver's License) drivers_license_expiration_date (Driver's License Expiration Date) -
driversLicFirstName  0012 (Driver's License) first_name_on_drivers_license (First Name) -
driversLicMiddleName  0012 (Driver's License) middle_name_on_drivers_license (Middle Name) -
driversLicLastName  0012 (Driver's License) last_name_on_drivers_license (Last Name) -
ssn  0032 (Social Security Card) social_security_number (Social Security Number) -
ssnFirstName  0032 (Social Security Card) first_name_on_social_security_card (First Name) -
ssnMiddleName  0032 (Social Security Card) middle_name_on_social_security_card (Middle Name) -
ssnLastName  0032 (Social Security Card) last_name_on_social_security_card (Last Name) -
passportFirstName  0033 (Passport) first_name_on_passport (First Name) -
passportMiddleName  0033 (Passport) middle_name_on_passport (Middle Name) -
passportLastName  0033 (Passport) last_name_on_passport (Last Name) -
nationality  0033 (Passport) citizenship (Citizenship) -
passportNumber  0033 (Passport) passport_number (Passport Number) -
passportIssueDate  0033 (Passport) passport_issue_date (Passport Issue Date) -
passportExpDate  0033 (Passport) passport_expiration_date (Passport Expiration Date) -
passportIssuingCity  0033 (Passport) city_of_issuance (City of Issuance) -
passwordsURL  0036 (Passwords) account_logins_website_address (Website) -
username  0036 (Passwords) account_logins_user_name (Username) -
password  0036 (Passwords) account_logins_password (Password) -
pin  0036 (Passwords) account_logins_pin_number (PIN Number) -
securityQuestion, securityAnswer  0036 (Passwords) security_question_complx (Security Question) -
rememberUsername  0036 (Passwords) password_remember_username (Remember Username) -
rememberPassword  0036 (Passwords) password_remember_password (Remember Password) -
stayLoggedIn  0036 (Passwords) password_stay_logged_in (Stay Logged In) -
addressType  0037 (Address) previous_address_category (Address Category) -
addressCompany  0037 (Address) previous_address_company (Company) -
streetAddress1  0037 (Address) previous_address_street (Street Address 1) -
streetAddress2  0037 (Address) previous_address_street_2 (Street Address 2) -
city  0037 (Address) previous_address_city (City) -
state  0037 (Address) previous_address_state (State) -
province  0037 (Address) previous_address_provinces (Province) -
postalCode  0037 (Address) previous_address_zip_code (Postal Code) -
country  0037 (Address) previous_address_country (Country) -
ccType  0040 (Credit & Debit Card) card_type (Card Type) -
ccNetwork  0040 (Credit & Debit Card) card_network (Card Network) -
ccName  0040 (Credit & Debit Card) credit_name_on_card (Name on Card) -
ccNumber  0040 (Credit & Debit Card) credit_card_number (Credit Card Number) -
ccExpiration  0040 (Credit & Debit Card) expiration_date (Expiration Date) -
ccSecCode  0040 (Credit & Debit Card) security_code (Security Code) -
healthInsPlanType  0084 (Health Insurance) health_care_plan (Health Care Plan) -
heathInsCoverageType  0084 (Health Insurance) coverage_type (Coverage Type) -
healthInsProvider  0084 (Health Insurance) health_insurance_provider (Insurance Provider) -
healthInsPolicyHolder  0084 (Health Insurance) member_name (Member Name) -
healthInsGroupNumber  0084 (Health Insurance) group_number (Group Number) -
healthInsMemberID  0084 (Health Insurance) member_id_number (Member ID Number) -
healthInsPolicyNumber  0084 (Health Insurance) health_policy_number (Policy Number) -
healthInsEmployer  0084 (Health Insurance) health_employer (Employer) -
membershipRewardsProgramName  0058 (Memberships & Rewards Programs) travel_rewards_program_name (Program Name) -
membershipRewardsNumber  0058 (Memberships & Rewards Programs) travel_rewards_membership_number (Membership Number) -
birthCertFirstName  0134 (Birth Certificate) first_name_on_birth_certificate (First Name) -
birthCertMiddleName  0134 (Birth Certificate) middle_name_on_birth_certificate (Middle Name) -
birthCertLastName  0134 (Birth Certificate) last_name_on_birth_certificate (Last Name) -
birthCertNumber  0134 (Birth Certificate) birth_certificate_number (Birth Certificate Number) -
birthCertBirthDate  0134 (Birth Certificate) birth_certificate_birthday (Date of Birth) -
birthCertGender  0134 (Birth Certificate) birth_certificate_sex (Sex) -
birthCertCity  0134 (Birth Certificate) birth_certificate_place_of_birth (City of Birth) -
birthCertCountry  0134 (Birth Certificate) birth_certificate_country_of_birth (Country of Birth) -
gender  0154 (Personal Information) personal_details_sex (Gender) -
ethnicity  0154 (Personal Information) personal_details_race_ethnicity (Race/Ethnicity) -
hairColor  0154 (Personal Information) personal_details_hair_color (Hair Color) -
maritalStatus  0154 (Personal Information) personal_details_marital_status (Marital Status) -
mothersMaidenName  0154 (Personal Information) personal_details_mothers_maiden_name (Mother's Maiden Name) -
primaryLanuage  0154 (Personal Information) personal_details_primary_language_spoken (Primary Language Spoken) -
otherLanguages  0154 (Personal Information) personal_details_other_language_spoken (Other Languages Spoken) -
birthDate  0171 (Birthday) birthday_birthday (Birthday) -