State and Country/Territory Picklists
State and Country/Territory Picklists is a Salesforce Setup feature that replaces the standard free-text Mailing State, Billing State, Shipping State, and corresponding Country fields on Account, Contact, Lead, Person Account, and User records with controlled picklists of ISO-standard values.
Definition
State and Country/Territory Picklists is a Salesforce Setup feature that replaces the standard free-text Mailing State, Billing State, Shipping State, and corresponding Country fields on Account, Contact, Lead, Person Account, and User records with controlled picklists of ISO-standard values. The feature improves data quality by preventing the kind of free-text variation that turns "CA," "Calif," "California," and "calif." into four separate values that need cleanup before any geographic analysis works.
Once enabled, every existing record in the org is scanned and the state and country values are mapped to their picklist equivalents wherever possible. Records with unmappable values (typos, abbreviations Salesforce does not recognize) are flagged for admin review. After cleanup, the picklist becomes the only way to enter state and country data, which permanently solves the data-quality problem at the source rather than requiring ongoing cleanup downstream.
Why this feature matters and how it works
Two address fields, two picklists
The feature creates two new picklists: State/Province (over 700 standardized values worldwide) and Country/Territory (around 240 entries based on ISO 3166-1). On every address field, the State picklist depends on the selected Country: choosing United States limits the State picklist to US states and territories, while choosing Germany limits it to German states (Bundesländer). The dependency works through Salesforce's standard dependent picklist mechanism, but admins do not see the dependency rules in the UI; they are managed by the platform. Each picklist value has an Integration Value (the abbreviated code stored in the database, like "CA" for California) and a Display Value (the human-readable label) that surfaces in the UI.
Integration values versus display values
The Integration Value is what gets stored in the BillingState and BillingCountry fields when a user picks an entry. Integration Values for US states are the two-letter codes (CA, NY, TX). Country Integration Values are the two-letter ISO codes (US, DE, IN). Display Values are the full names (California, New York, Texas, United States, Germany, India). API consumers (Apex callouts, integrations, Data Loader exports) see the Integration Values, while UI users see the Display Values. This dual representation is what enables compatibility with external systems that store state and country in standardized codes while keeping the user-facing experience friendly.
Enablement process and address scanning
Enabling State and Country/Territory Picklists is a two-stage Setup process. Stage one is the address scan, which runs against every Account, Contact, Lead, Person Account, and User record. The scanner maps current free-text values to their picklist equivalents based on a built-in dictionary plus any custom mappings the admin defined. The output is a report showing which records have clean mappings and which need manual review. Stage two is enabling the picklists, which converts the fields from text to picklist and locks in the controlled-vocabulary behavior going forward. Most orgs leave a few weeks between the scan and the activation to clean up the unmappable records.
Adding, hiding, and customizing picklist values
The standard picklist values cover most real-world geography, but orgs occasionally need to add new values (territories, custom-named regions) or hide values they do not do business in. From the State and Country Picklists Setup page, admins can deactivate values to hide them from new selections while preserving their use on historical records. New values can be added with custom Integration Values and Display Values. The Hidden flag is reversible. Deactivating a value does not invalidate records that already store that value; it only removes the value from the picker for future selections. This makes cleanup safe in either direction.
Impact on validation rules, formulas, and reports
Validation rules and formulas that reference state and country fields need to be reviewed before enabling the picklists. Rules that compare against text values like "California" need to be updated to compare against "CA" (the Integration Value), since the picklist stores the abbreviated code. Reports that group by state or country will start grouping by Integration Value unless modified to use the picklist label. Most orgs handle this by exporting all validation rules and formulas mentioning the address fields, doing a search-and-replace, and re-deploying through Change Sets or DevOps Center. Forgetting this step results in rules that silently stop firing the right way after enablement.
Multi-language and localization
Country and state Display Values are localized to the user's language setting. A French-language user sees "Allemagne" instead of "Germany" and "États-Unis" instead of "United States," while the Integration Value stored in the database remains the standard ISO code regardless of language. This is the correct behavior for global orgs: users see addresses in their own language while integrations and reports use consistent codes. Admins do not need to maintain translations themselves; Salesforce ships the localized Display Values for all supported languages. Custom-added picklist values do require admins to provide translations through the Translation Workbench if the org operates in multiple languages.
Common rollout pitfalls
The most common pitfall is enabling picklists without auditing existing automation, which causes processes and validation rules to fail or silently misbehave. Other pitfalls: integrations that send Display Values instead of Integration Values to the BillingState field, which fail with confusing error messages; old Visualforce pages that hardcode the state field as a text input, which need to be updated to use the standard state picklist component; and report subscribers who notice that their grouped reports now show "CA" instead of "California" and worry that something broke. Each of these is straightforward to fix, but together they make the rollout feel larger than the Setup change implies.
Ongoing maintenance and cleanup
After enablement, the picklist is the entry point but data quality maintenance is still required. New countries occasionally need to be added when the business expands. Old states that the business no longer serves should be deactivated to keep the picklist short. Re-running the address scan annually catches integration-introduced bad data, because some external systems still slip free-text values into address fields through legacy API paths. The standard maintenance cadence is a quarterly review of the picklist values for activeness and an annual address scan to detect drift. For orgs with high data turnover, monthly automation that flags records with unusual state and country combinations gives the data team time to fix issues before they accumulate. None of this is heavy work, but skipping it for three or four years allows the kind of drift that the picklists were meant to prevent.
Enable State and Country Picklists safely
Enabling these picklists is a one-way improvement to data quality, but the rollout has several moving parts. The standard sequence below avoids the common pitfalls and gives the org a clean activation rather than a panicked rollback.
- Run the address scan in sandbox first
From Setup, navigate to State and Country/Territory Picklists and run the address scan. The scan completes in minutes for small orgs and hours for large orgs with millions of records. Review the output report: which records mapped cleanly, which need manual review. Build a cleanup plan for the unmappable records, either correcting them manually for small volumes or using Data Loader for larger volumes.
- Audit and update validation rules, formulas, automations
Search the org for every validation rule, formula field, workflow rule, process, Flow, and Apex class that references BillingState, BillingCountry, MailingState, MailingCountry, ShippingState, or ShippingCountry. Update text comparisons from full names ("California") to Integration Values ("CA"). Run these changes through the standard test cycle. Document any places where automation now needs adjustment so the same changes can be repeated in production.
- Configure custom values and deactivate unused entries
Review the standard picklist values for any countries or states the business does not operate in. Deactivate them to keep the picklist short. Add custom values for any geographies Salesforce does not ship by default. Test the customizations against a sample of records to confirm the address fields look right. Save the configuration and prepare to replicate it in production.
- Enable in production during a low-activity window
Schedule production enablement during a low-traffic window, ideally a weekend or after-hours period. Run the address scan in production, apply the cleanup plan to the unmappable records, then enable the picklists. Communicate the change to integration owners and data teams the same day so they can verify their downstream systems still work correctly. Monitor the Setup Audit Trail and any custom error logs for the next several days for any automation that misbehaves.
- Once enabled, picklists cannot be reverted to free-text fields without a Salesforce Support engagement and significant data implications. Treat the enablement as permanent.
- Validation rules and formulas need to use Integration Values, not Display Values. Rules that compare against full state names break silently on enablement.
- The address scan does not detect all unmappable values. Manual review of the report is required because some records contain valid-looking strings that the scanner accepts but that map to the wrong state or country.
- Integrations that POST records with full state names like "California" fail after enablement. They must be updated to send "CA" or rely on the platform's text-to-picklist matching, which is not always available.
- Visualforce and Aura components that build custom address forms must be updated to use the standard state picklist components. Custom text inputs cause silent data corruption.
Trust & references
Cross-checked against the following references.
- State and Country/Territory PicklistsSalesforce Help
- Enable and Disable PicklistsSalesforce Help
Straight from the source - Salesforce's reference material on State and Country/Territory Picklists.
- State and Country PicklistsSalesforce Help
- Scan AddressesSalesforce Help
- Customize PicklistsSalesforce Help
Hands-on resources to go deeper on State and Country/Territory Picklists.
About the Author
Dipojjal Chakrabarti is a B2C Solution Architect with 29 Salesforce certifications and over 13 years in the Salesforce ecosystem. He runs salesforcedictionary.com to help admins, developers, architects, and cert/interview candidates sharpen their fundamentals. More about Dipojjal.
Test your knowledge
Q1. Why is understanding State and Country/Territory Picklists important for Salesforce admins?
Q2. In which area of Salesforce would you typically find State and Country/Territory Picklists?
Q3. What is the primary benefit of State and Country/Territory Picklists for Salesforce administrators?
Discussion
Loading discussion…