Use API Name to Keep Picklist Integration Safe

Whenever possible, try to use the declarative or standard feature such as Approval Processes, Visual Flows, and Workflows because these components are already fully optimized by the; therefore, it won’t count against most of the governor limits but in some cases business may need complex logic; then we can go for the programmatic features.

For a developer, it is very painful to rename a picklist value because he needs to check the reference of this picklist value in the existing system including validation rule, workflow rule, apex code etc., but from Spring ’17 release, Salesforce changed the picklist behavior to protect our picklist integrations. Now, each picklist value is represented with a label and an API name (like the name-value pair data representation):

  1. Picklist value’s label – displayed in a record through UI.
  2. Picklist value’s API name – used internally on metadata level.

Image 1: Picklist value API name automatically created, when you add values to the picklist.

picklist integration

Image 2: We can modify the picklist value’s label and API name by clicking edit link.

picklist integration

Image 3: Preventing Picklist Value API Name from being changed. (go to Administer -> Data Management -> Picklist Settings).

picklist integration

SOQL consideration 

1. By default, SOQL query returns with picklist value API Name.


Select Enrollment_Type__c from Lead



2. To get the picklist label via SOQL.


Select ToLabel(Enrollment_Type__c) from Lead


Billing Partner

Picklist Metadata API Changes (39.0 and above)








      <label> Billing Partner </label> 




Schema.PicklistEntry object

Use the PicklistEntry Class to retrieve picklist value’s label and API name dynamically.

Schema.DescribeFieldResult fieldResult = Account.PicklistField__c. getDescribe(); 

List<Schema.PicklistEntry> values = fieldResult.getPicklistValues(); 

for( Schema.PicklistEntry v : values) { 

      System.debug('Picklist Value Label:' + v.getLabel()); 

      System.debug('Picklist API Name:' + v.getValue()); 


getLabel() – will return a picklist value’s label.

getValue() – will return a picklist value’s API Name, as it used to do before.


We can keep the picklist integration safe by referring picklist value’s API name in the apex code, validation rule and Workflow rule etc. So, by any time developer/admin can change the picklist value’s label would not impact/break any integration.

Reference Link: 



About MST

At MST Solutions our cornerstone is to adapt, engage and create solutions which guarantee the success of our clients. The talent of our team and experiences in varied business verticals gives us an advantage over other competitors.

Recent Articles

Work with us.

Our people aren’t just employees, they are key to the success of our business. We recognize the strengths of each individual and allow them time and resources to further develop those skills, crafting a culture of leaders who are passionate about where they are going within our organization.