Use an alternate key to reference a record

You will use alternate keys with data integration scenarios to perform data operations where you don't know the primary key value of a Dataverse record. You can only use alternate keys for tables where they are defined. Most Dataverse tables will not have alternate keys unless they have been customized to include them.

To understand how to define and identify alternate keys for a table, see the following topics:

You can use alternate keys using either the Datverse Web API or the Dataverse SDK for .NET.

When using the Web API you reference a specific record using a URL and then use the POST, PATCH, or DELETE Http methods to perform the data operation. You also use URLs to set values for single-valued navigation properties using the @odata.bind syntax, or as parameters to functions and actions.

The following table provides examples showing how to reference records using relative urls:

Situation Example
With a primary key /accounts(00000000-0000-0000-0000-000000000001) OR
See note below about systemuser and team entity types
With single alternate key /accounts(accountnumber='ABC123')
With multi-part alternate keys /contacts(firstname='Joe',emailaddress1='')
With an alternate key that uses a lookup column /accounts(_primarycontactid_value=00000000-0000-0000-0000-000000000002)
When an alternate key is defined for a lookup column, you must use the name of the corresponding Lookup Property. A lookup property follows the following naming convention: _<name of single-valued navigation property>_value.


Because of how systemuser and team entity types inherit from the principal entity type, you cannot use a named primary key to reference these entities. The primary keys for both of these entities is ownerid, rather than systemuserid or teamid. The principal entity type doesn't support GET operations. More information: EntityType inheritance

Exceptions when using alternate keys with the Web API

You have to be aware of the following conditions and possible exceptions when using alternate keys:

  • If you specify a column that is not defined as a unique key, an error will be thrown indicating that use of unique key columns is required. The error message is: The key in the request URI is not valid for resource 'Microsoft.Dynamics.CRM.<table logical name>'. Ensure that the names and number of key properties match the declared or alternate key properties for the resource 'Microsoft.Dynamics.CRM.<table logical name>'.

More information: Retrieve using an alternate key

See also

Define alternate keys for a table
Use change tracking to synchronize data with external systems
Use Upsert to insert or update a record