Mass Update Addresses
Mass Update Addresses is the Salesforce Setup tool that updates the Country, State, or Country Code field on Account, Contact, Lead, or Person Account records in bulk based on a CSV mapping.
Definition
Mass Update Addresses is the Salesforce Setup tool that updates the Country, State, or Country Code field on Account, Contact, Lead, or Person Account records in bulk based on a CSV mapping. The tool exists to support the State and Country Picklist migration: when an org enables State and Country Picklists for the first time, all existing address records use free-text Country/State values that need to be standardized to picklist entries. Mass Update Addresses provides the bulk normalization path, mapping the existing free-text values to the new standardized picklist values.
The tool is most useful during a one-time State and Country Picklist enablement. After enablement, individual record edits use the picklist directly, so the tool's role becomes limited to bulk cleanup. Some orgs run it periodically as data quality maintenance: catch records with deprecated country names or alternate state spellings, normalize them. The tool is one piece of a broader address data quality program; pair with Address Standardization or Data.com Clean for fuller normalization.
How Mass Update Addresses works
Why State and Country Picklists exist
Free-text Country and State fields produce messy data: USA, United States, U.S., U.S.A. all refer to the same country. Reports filtering by country see them as different values, making aggregation impossible. State and Country Picklists enforce a canonical set of values, ensuring consistency. Once enabled, new records use picklists; existing records need migration through tools like Mass Update Addresses.
The migration scenario
Most orgs hit Mass Update Addresses once: when first enabling State and Country Picklists, they need to normalize existing free-text values across thousands of records. The tool generates the mapping (USA > United States, U.S. > United States, etc.) and applies it across the affected objects. After the one-time migration, the tool sits unused unless a new normalization need arises.
Object scope
The tool supports Account, Contact, Lead, Person Account address fields. Custom objects with address fields are not supported. For custom object addresses, use Data Loader with a pre-built mapping CSV. The standard tool covers the most common address-bearing objects, which is sufficient for most organizations.
Mapping CSV format
The tool accepts a CSV with original-to-canonical mappings. Build the CSV by extracting unique current values, mapping each to the appropriate picklist entry. The mapping is many-to-one: multiple variants (USA, U.S., U.S.A.) map to one canonical value (United States). Bad mappings produce incorrect updates; review the mapping before uploading.
Preview before applying
The tool shows a preview of changes before applying. Verify the preview matches expectations; bad mappings or unexpected values may surface here. Confirm spot-check records show the right new value before clicking Apply.
Interaction with triggers and workflow
Address updates fire triggers and workflow on the affected objects. For an Account with a trigger on BillingCountry, every updated record fires the trigger. Bulk updates of tens of thousands of records can hit governor limits; plan for batching and any heavy automation.
Post-migration considerations
After Mass Update Addresses completes the migration, validate by querying for any records still on free-text values. Spot-check sample records to confirm correctness. Configure validation rules requiring picklist values to prevent regression; without rules, future imports may reintroduce free-text values.
Run an address picklist migration
Running Mass Update Addresses is the bulk normalization step in a State and Country Picklist migration. The steps below cover the full workflow from extraction to post-migration validation.
- Enable State and Country Picklists
Setup > State and Country/Territory Picklists > Enable. The platform configures the picklist values; existing free-text remains.
- Extract current values
Query Account, Contact, Lead for unique BillingCountry and BillingState values. Get the full list of current free-text values needing migration.
- Build the mapping CSV
For each current value, map to the canonical picklist entry. Many variants map to one canonical (USA, U.S., U.S.A. all map to United States).
- Open Mass Update Addresses
Setup > Data > Mass Update Addresses. Upload the mapping CSV. Select object scope.
- Preview changes
Review the preview. Spot-check records for correctness. Confirm before applying.
- Apply the updates
Run the update. Monitor for governor limit failures on large volumes; batching may be needed.
- Validate and add rules
Query for any remaining free-text values. Add validation rules requiring picklist entries to prevent regression.
Account, Contact, Lead, Person Account. Custom objects not supported.
Current-to-canonical mapping for each free-text value.
BillingCountry, MailingCountry, etc. Selected per object.
BillingState, MailingState, etc. Often run alongside Country.
Records and proposed values shown before commit.
- Custom objects not supported. For custom object addresses, use Data Loader.
- Bad mappings produce silent incorrect updates. Spot-check the preview carefully.
- Triggers fire on every updated record. Plan for governor limits on large volumes.
- Post-migration validation rules are essential. Without them, future imports reintroduce free-text values.
- The tool is primarily for one-time migration. Ongoing address quality needs Data.com Clean or similar.
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. In which area of Salesforce would you typically find Mass Update Addresses?
Q2. Can a Salesforce admin configure Mass Update Addresses without writing code?
Q3. What is the primary benefit of Mass Update Addresses for Salesforce administrators?
Discussion
Loading discussion…