What restricted means
A restricted picklist accepts values from its configured value set and, where applicable, the values enabled for the record type. This prevents spelling variants and accidental categories. Salesforce Help also documents limits for active and inactive values, so a field with a long history needs lifecycle management.
Restricted does not mean “the label visible on screen is always accepted.” Your API may need the value’s API name, and a record type may expose only a subset.
What unrestricted means
An unrestricted picklist is more permissive about incoming values, but that flexibility can produce vocabulary drift. One source may send “Mid market,” another “Mid-market,” and a third “midmarket.” Humans understand the relationship; formulas, reports, and exact-match integrations may not.
Unrestricted is not a substitute for validation. Your integration should still maintain a source mapping and reject values that violate business rules.
Decision table
| Situation | Better default | |---|---| | Stage, status, or lifecycle state | Restricted | | Values drive Flow or validation | Restricted | | External catalog grows frequently | Consider unrestricted with governance | | Free-form imported classification | Consider text field instead | | Multi-org controlled vocabulary | Restricted plus metadata deployment |
If the field is really an uncontrolled description, a text field may be clearer than an unrestricted picklist.
Why integrations fail
The most common failures are sending a label instead of an API name, using a value not selected for the target record type, sending null to a required field, and forgetting controlling values for a dependent picklist. The error may look like a reason to disable restriction, but that can hide a mapping defect.
Build a metadata lookup for each object and field. Include API name, label, active status, record-type availability, dependency information, and whether the field is required in the transaction.
Record types matter
A value can be defined globally but unavailable to a particular record type. An administrator can edit the record type and move values from Available Values to Selected Values. Check this in every environment where the integration runs.
Do not broaden every record type simply because one API job needs a value. Ask whether the record type should allow the value and whether downstream automation expects the old restriction.
API-name mapping
Keep source values separate from Salesforce API names:
The exact right-hand values must come from your org’s metadata. Do not assume labels, capitalization, or punctuation. Test a valid value, an unknown value, and a value that is globally valid but record-type unavailable.
{
"won": "Closed_Won",
"lost": "Closed_Lost"
}
When changing the setting is safe
Changing to unrestricted can be reasonable for a field whose values are informational, whose source vocabulary is deliberately open, and whose reports normalize values. It should still have an owner, a cleanup schedule, and a documented maximum size. Salesforce publishes picklist limits; ignoring them can create a future deployment problem.
Changing to restricted is a data-quality project. First inventory existing values, map variants, and fix automation. Then enforce the value set and monitor rejected writes.
Testing plan
Run tests through the same API path used in production. Create and update records under each relevant record type. Test blank values, dependency combinations, invalid API names, and metadata changes. Assert both response errors and final field values.
Add a release check that compares the required value set with the target org. A code deployment should not be considered complete if the metadata it relies on is missing.
Governance that lasts
Name a business owner for the vocabulary. Document who can add or deactivate values, how labels and API names are changed, and how historical records are treated. For shared picklists, coordinate changes across objects and integrations.
Monitor values that appear in the source but not in metadata. A review queue is safer than silently creating categories or silently mapping everything to “Other.”
The trap: changing a restricted picklist to unrestricted to stop one error. That may turn a visible integration failure into invisible reporting drift.
A migration path between settings
If the current field is unrestricted but the organization wants control, first export distinct values, group spelling variants, choose canonical API names, and update downstream formulas. Add missing values to the controlled set, test record types, and only then enforce restriction.
If the current field is restricted but a legitimate external value arrives, check whether it should be added to the value set, selected on the record type, or transformed by the integration. Each answer has a different governance owner.
Track unknown incoming values, rejected saves, manual corrections, and report variants. These measures show whether the chosen setting is protecting data or creating unnecessary operations.
Review the field with the owners of automation, reporting, integrations, and data governance together. A setting that helps an import team may undermine a Flow or dashboard. Agree on the canonical vocabulary, who approves new values, and how old variants are corrected before changing the field in production.
For a high-volume integration, test the rejected-value path under load. The system should place invalid rows in a review report without retrying them endlessly. A controlled failure is evidence that the restriction is working; an unbounded retry is an integration design flaw.
Document whether labels are translated for users while API names remain stable. Translation changes should not require rewriting data mappings.
Review inactive values periodically and remove obsolete vocabulary only after checking historical reports and integrations. A clean list is useful, but deletion without impact analysis can break deployments or old imports.
Schedule this review with the field owner and integration owner together.
Record the decision and next review date in the governance log.
Before changing the setting, take a distinct-value export and identify integrations that write the field. Include historical reports, Flow criteria, validation formulas, and external mappings in the impact review. A picklist decision is successful only when the new vocabulary remains understandable to both users and downstream systems.
Decide with an ownership test
Before making a picklist unrestricted, name the person who will approve new vocabulary, clean variants, and repair downstream mappings. If no owner exists, the setting is likely to create hidden data-quality work. For an integration-owned field, a restricted list plus a review queue usually gives a clearer failure than silently accepting every incoming spelling.
Where these facts come from
