Dynamics 365 – Alternate keys can stop duplicates

Without reflection, we go blindly on our way, creating more unintended consequences, and failing to achieve anything useful. Margaret J. Wheatley

Alternative keys allow you to lookup records without having the guid of the record, they give a method to stop users adding duplicates, speed up Dynamics 365 searching and are useful for integrating Dynamics 365 with external services/systems.

Key facts

  • Alternate keys can stop duplicates
  • Alternate keys can increase record lookup speed
  • Alternative keys allow you to lookup records without a guid but with information which makes an alternate key.  E.g. lookup a person using surname and email.
  • Work well with upsert, allowing you to find a record and either update or create
  • Can sometimes cause problems when trying to remove them solutions
  • Added in Dynamics CRM 2016 and available in Dynamics 365 online and on premise

What is an alternate key?

An alternate key can be added to an entity and can be made up of one or more fields on the entity.  Alternate keys use database indexes, this has the benefit of making records unique by stopping duplicates and increasing performance when retrieving records with an alternate key.

Alternate key facts

  • Each entity can have 5 alternate keys
  • You can only use strings, decimals and integers (whole number) to create an alternate key
  • There is a maximum key size to be aware of
  • After creating an alternate key, an async job will create the index and the status will be pending, In Progress, Active and failed.  If you have a lot of records this could take a long time.
  • You can retrieve an alternate key using RetrieveEntityKeyRequest, you delete an alternate key using DeleteEntityKeyRequest.

To learn more about alternate key read the posts

Stopping Duplicates

Alternate keys is they give a way to stop users adding duplicate records.  When you add an alternate key and a user tries to add a duplicate, Dynamics 365 will stop the user from adding the record and show the warning below.







This is better than out of the box duplicate stopping functionality which only warns the user but lets them add a duplicate.  The alternative is to stop duplicates via a plugin, which takes more effort and has a maintenance overhead.


It’s difficult to remove alternate keys from managed solutions, I have had problems where Dynamics 365 didn’t want to remove the alternate key.

The limitation of using numbers and strings can leave you frustrated when you want to use a date field.  You can work aaround this by converting a date field to a string but it‘s messy.

picture from here