Mass Update Addresses
Mass Update Addresses is a Salesforce Setup tool that converts the country and state or province values on existing records to standardized values during the State and Country/Territory Picklists rollout.
Definition
Mass Update Addresses is a Salesforce Setup tool that converts the country and state or province values on existing records to standardized values during the State and Country/Territory Picklists rollout. You reach it from Setup under Data Management, and it works on the address fields of Account, Contact, Lead, and Person Account records. Instead of editing thousands of rows by hand, you map each free-text value (such as USA or U.S.) to a single canonical picklist entry and apply the change in bulk.
The tool fits one specific point in the picklist project. After you scan your org and convert your customizations, but before or just after you enable picklists, you still have stored text values that have not been re-saved. Mass Update Addresses brings those records onto the standardized list so reports, list views, and filters group by one consistent value per country and state.
How Mass Update Addresses fits the picklist rollout
Where it sits in the four-stage rollout
Turning on State and Country/Territory Picklists is not a single switch. Salesforce breaks it into four stages: scan, convert, enable, and configure. The scan stage runs a discovery report so you can see where state and country data lives and which list views, reports, and code reference it. The convert stage is where you standardize the actual record values, and Mass Update Addresses (along with the related Convert tool) is the engine for that work. Enabling flips the picklists on, and configuring lets you set defaults and active values afterward. Running Mass Update Addresses out of order causes pain. If you enable picklists before converting, records that have not been re-saved keep their original text, and any record someone saves picks up an integration value that may not match the text it replaced. Doing the bulk conversion first means the data is already clean when the picklists go live. Treat the tool as one step in a sequence, not a standalone cleanup utility you reach for whenever addresses look messy.
What the tool actually changes
The tool operates on the country and the state or province portion of standard address fields. You start by choosing whether you are updating the country, the state, or both, because the two are linked and Salesforce will not save a state without a matching country. It then groups your existing records by the distinct text values it finds, so you are not staring at one row per record. You see USA grouped together, United States grouped together, and so on. For each group you pick the standard value it should become. When you apply the change, every record in that group is rewritten to the chosen entry. The point is consistency. Free-text fields let people type USA, U.S., U.S.A., and United States, and a report filtering on country treats all four as separate buckets. After conversion they all resolve to one canonical country, so aggregation finally works. The tool does not touch street, city, or postal code. Those stay free text because there is no picklist behind them.
Integration values and why they matter
Every standard state and country in the picklist carries two things: a display label that users see and an integration value that systems use. The integration value is a customizable text string tied to the underlying code, and it defaults to the full ISO name, like United States or California. This matters because anything built before picklists existed reads or writes the old text. API calls, data loads, formula fields, and outbound integrations all expect the value they were coded against. If your integrations sent United States, set the integration value to United States so they keep working after the switch. When Mass Update Addresses converts a record, the field stores the integration value, not just the friendly label. So your mapping decisions ripple into every downstream system. Review integration values before you convert, not after. Changing them later means re-touching records and re-testing integrations. You can move integration value changes between a sandbox and production using the Metadata API, since these picklists are not supported in change sets or packages.
Which objects and fields are in scope
Mass Update Addresses covers the standard address-bearing objects: Account, Contact, Lead, and Person Account. The broader State and Country/Territory Picklists feature reaches further, into Campaign Member, Contract, Order, Quote, and Service Contract, across the shipping, billing, mailing, and other address fields. Custom objects with address-style fields are not handled by this Setup tool. If you store addresses on a custom object, you convert those values with Data Loader using a prepared CSV that maps each old text value to the correct integration value. The standard coverage is wide enough for most orgs, because the bulk of address data lives on accounts and contacts. Salesforce ships 235 countries and territories as standard, plus the states and provinces for countries like the United States, Canada, Australia, Brazil, China, India, Ireland, Italy, Japan, and Mexico. If your business operates somewhere without standard state codes, you can add states under that country before you convert, so the values you need actually exist in the list when you map records to them.
Planning the conversion safely
A bulk address update is a data change against live records, so plan it like one. Start in a sandbox that mirrors production, run the full scan, and read the discovery results before you convert anything. Look for surprises: blank countries, typos, and values that map to more than one real country. Each rewritten record can fire triggers, flows, validation rules, and workflow tied to the address fields. Updating tens of thousands of accounts at once can trip governor limits or send unwanted notifications if automation reacts to address changes. Check what listens to BillingCountry, MailingState, and the rest, and decide whether to pause any automation during the run. Take an export of the affected fields first so you have a rollback reference. Validation rules are a common trap. A rule that requires a country whenever a state is present will block conversions where the data is incomplete, so you may need to clean those records before the bulk pass. Work in waves rather than one giant operation when volumes are high, and verify each wave before moving on.
After the conversion: keeping data clean
Finishing the bulk pass is not the end. Once picklists are live, new and edited records use them automatically, which is the whole point. The risk is regression through the side doors. Imports, the Data Import Wizard, Data Loader jobs, and API integrations can still write text that does not match a standard value if you let them. Add validation rules or rely on the picklist enforcement so future records cannot reintroduce variants like U.S. or Calif. Re-run the scan periodically to confirm nothing has drifted, and query for records whose country or state sits outside the standard set. Person Account conversions deserve a second look, since a person account carries both account-style and contact-style address fields and people sometimes forget one side. Spot-check a sample across objects after the run, compare counts before and after, and confirm a few records show the integration value you expected. Clean address data pays off quietly: territory assignment, regional reporting, and downstream integrations all behave because every record finally speaks the same vocabulary.
Convert addresses during a picklist rollout
Run Mass Update Addresses as part of the State and Country/Territory Picklists conversion. Do this in a sandbox first, scan your data, then convert values in controlled waves before relying on it in production.
- Scan your org first
From Setup, open State and Country/Territory Picklists and run the scan. Review the discovery report to see every distinct country and state value, which records hold them, and which list views, reports, and code reference the fields.
- Set integration values
Before converting, confirm the integration value for each standard country and state matches what your existing integrations send and receive. Defaults follow the full ISO names. Adjust them so API calls, data loads, and formulas keep working after enablement.
- Open the conversion tool
Choose to convert your identified data. Decide whether you are updating country, state, or both. The tool groups existing records by their current text value so you map each group once rather than editing records individually.
- Map and apply in waves
For each text value, pick the standard value it should become, then apply. Work through high-volume countries in batches, and let any triggers or flows settle between waves rather than converting everything in one pass.
- Verify and lock it down
Query for records still on non-standard values, spot-check samples across Account, Contact, Lead, and Person Account, and add validation rules so imports and integrations cannot reintroduce free-text variants later.
Controls which part of the address you convert. State and country are linked, so a state cannot be saved without a matching country in scope.
The Setup tool handles Account, Contact, Lead, and Person Account. Use Data Loader with a mapping CSV for custom objects, which the tool does not cover.
The text stored on the record after conversion. Set it to match legacy integrations before running, since it is what downstream systems read.
- Records not re-saved since you enabled picklists keep their original text values, so convert before relying on the data rather than assuming enablement cleaned it.
- Every rewritten record can fire triggers, flows, validation rules, and workflow on the address fields, so high-volume runs can hit governor limits or spam notifications.
- Custom objects with address fields are out of scope; convert those with Data Loader using a prepared mapping CSV.
- These picklists are not supported in change sets or packages, so move integration value changes from sandbox to production with the Metadata API.
Trust & references
Cross-checked against the following references.
- Mass Update AddressesSalesforce
- Convert State and Country/Territory DataSalesforce
Straight from the source - Salesforce's reference material on Mass Update Addresses.
Hands-on resources to go deeper on Mass Update Addresses.
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…