Something I’m consistently surprised to see is the misunderstanding around the two different types of keys in Salesforce. Every record has two keys: a 15-digit, case-insensitive key, and an 18-digit case-sensitive key.
So what’s the difference?
The 18-digit key is made up of two parts:
- The 15-digit key; and
- a 3-digit capitalization code for the previous 15 digits.
Why is this important?
When you’re doing any API work in Salesforce, this will eventually come up. And, depending on which version you’re using, you will have to be aware of different things:
API versions prior to 2.0: The ID of a record is always a 15-character case-sensitive ID and should not be compared in a case-insensitive manner.
API versions 2.0 and higher: The API can return either a case-sensitive or a case-insensitive ID field value. The case-insensitive ID is identical to the 15-character case-sensitive ID with three extra characters appended to indicate the case of each of the original 15 characters. When inserting or updating records, the API accepts either the 15-character case-sensitive ID or the 18-character case-insensitive ID. When querying or searching records using the API, you must specify a value of “1” for the “useCaseSafeIDs” parameter to indicate that you want the API to return case-insensitive IDs. If you do not specify the “useCaseSafeIDs” parameter, you automatically receive case-sensitive IDs.
API 2.5: Defaults to 18 characters on the ID (case safe) and provides no option to use the 15-character ID explicitly.
The “Reports” tool queries the database directly and therefore returns a 15-character case-sensitive ID. Tools such as the Data Loader, Demand Tools or the Weekly Data Export service will export records with the 18-character ID.
So what do you have to do to prepare yourself? First, you need to know which API version you’re dealing with. You can check this in Salesforce in XML by going to /services/data/ on your instance.
If you want to know which release you’re on, you can also click your Home tab and check out the orange box that floats in the top right. As you see, we’re on Winter ’16. The corresponding API number is 35.0, so now I have my answer.
That’s why yesterday when I was comparing a Key in a Custom Settings object I had created, my code was throwing an exception: My SOQL query was looking for a custom setting entry with the 18 digit key but I had given it the 15-digit key. Once I examined output in Developer Console I realized what I had forgotten. Making this change rectified my issue.
So how do you get the 18-digit key?
Ahh, well that’s pretty easy. On the object you’re working on, create a custom formula field called “Api Key” and put this in the formula field:
And voila! Make the field visible to System Administrator only and add it to the layout. You can now copy it off the record form!