All about alternate keys in Dynamics CRM

Retrieving metadata items by name is generally easier because you probably already have some reference to this item name in your code. The following table lists the alternate key properties for retrieving metadata items by name. The primary benefit of this feature is to provide an alternative way to identify a CRM record.

Traditionally we use CRM entity’s primary key field to identify a CRM record, which stores GUID values and this becomes a challenge when we try to integrate CRM data with third-party database or application systems, which might use some natural keys to identify a record. It provides  much easier way to code while integrating with 3rd party systems.

Metadata item Alternate Key Example
Entity LogicalName GET /api/data/v8.2/EntityDefinitions(LogicalName=’account’)
Attribute LogicalName GET /api/data/v8.2/EntityDefinitions(LogicalName=’account’)/Attributes(LogicalName=’emailaddress1′)
Relationship SchemaName GET /api/data/v8.2/RelationshipDefinitions(SchemaName=’Account_Tasks’)
Global Option Set Name GET /api/data/v8.2/GlobalOptionSetDefinitions(Name=’metric_goaltype’)

When creating an alternative key, CRM kicks off a system job that creates a db index at CRM database server side, the purpose of the db index is to enforce the uniqueness of key while offering an optimal query performance. Depending on the number of existing CRM records that you have for the concerned entity in CRM system, it could take a while to create the index. You can see the most recent status of the index creating job. Only the below three fields could be created as keys and over all we can create 5 keys for an entity.

  • String
  • Integer
  • Decimal

Alternate keys could be used in the two scenarios as below

  • Update
  • Upsert (a new capability introduced in CRM 2015 Spring release, which will be further discussed in a following post)

Let us see performing an update operation through code with alternate keys

using (var service = new OrganizationService(crmConnection))


// Use alternate key (accountnumber) field to identify an account record

Entity account = new Entity(“account”, “accountnumber”, “ACT-12345”);

// Set new credit limit;

account[“creditlimit”] = new Money(100000);

// Entity reference using alternate key (emailaddress1) on contact entity

account[“primarycontactid”] = new EntityReference(“contact”, “emailaddress1”, “”);

UpdateRequest request = new UpdateRequest() { Target = account };

UpdateResponse response = (UpdateResponse)service.Execute(request);


In the case that a CRM record cannot be found using the provided key value, you will receive the following error exception (where account is the entity name).

References: Alternate keys from MSDN




Author: Pavan Mani Deep Y

Technology geek who loves sharing my leanings, quick tips and new features on Dynamics 365 & related tools, technologies. An Azure IOT Enthusiast....

3 thoughts on “All about alternate keys in Dynamics CRM”

  1. Wow! This could be one particular of the most useful blogs We have ever arrive across on this subject. Actually Fantastic. I am also a specialist in this topic so I can understand your hard work.


Leave a Reply

Fill in your details below or click an icon to log in: Logo

You are commenting using your account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s


Sharing thoughts and challenges on Power Platform & Azure along with respective solutions put together...

SharePains by Microsoft MVP Pieter Veenstra

Microsoft 365, Power Platform, SharePoint, Teams, Azure and Dynamics

D365 Demystified

A closer look at Microsoft Dynamics 365.

Vicky Rodgers - Microsoft Dynamics 365

Everything Microsoft Dynamics 365 for Customer Engagement

XRM Tricks (Power Platform & Dynamics CRM )

Power Platform & Dynamics CRM

Microsoft Dynamics 365 UK MCT

All about Microsoft Dynamics 365

High Voltages

Arduino | ESP | Raspberry pi | IoT

Mihail's space

Just another site

Arun Potti's MS CRM blog

Microsoft Dynamics CRM

Sander van de Velde

Microsoft MVP Azure | IoT Platform Architect | Speaker about IoT | Let me add some value

Power Platform Blog

Author : Dharanidharan Balasubramaniam

That API Guy

Making the world a better place one PowerApp/Flow at a time!

Dynamics Back Page

Tips, Tricks, and General Musings on Dynamics 365 (CRM), the Power Platform, Power Apps, Power Automate, Power BI and related technologies

Azure Integration services for Dynamics 365

Azure Integration services for Dynamics 365 Unified Operations, Logic Apps, Azure Functions, REST

Power Maverick

Incredible journey into #Dynamics365, #CDS, #PowerApps #Azure and all good stuff that #Microsoft releases

Unleashing CRM

My Technical Thoughts about Microsoft Dynamics CRM- Unleashed

Srikanth Alluri

My experiences in & around Power Platform + Azure

Debajit's Power Apps & Dynamics 365 Blog

All about Power Apps & Dynamics

Rajeev Pentyala - Microsoft Power Platform

Sharing my knowledge on Power Platform, Dynamics 365, Azure & .Net Stack

Bansal Blogs - Dynamics 365, PowerApps, Microsoft Flows, Power BI

Programming demands a lot more than simple mastery in tools and technologies

%d bloggers like this: