You are using an older browser that might negatively affect how this site is displayed. Please update to a modern browser to have a better experience. Sorry for the inconvenience!

Use API Name to Keep Picklist Integration Safe

By: Venkata

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: