Web API types and operations
Note
Effective November 2020:
- Common Data Service has been renamed to Microsoft Dataverse. Learn more
- Some terminology in Microsoft Dataverse has been updated. For example, entity is now table and field is now column. Learn more
This article will be updated soon to reflect the latest terminology.
In order to use the Web API you need to find information about what is available for you to use. The service describes itself via service and metadata documents that you can access. This topic will introduce important concepts and describe how you can find the information you need using documentation generated from the service and metadata documents as well as the documentation of the system entity types, functions, and actions.
Terminology
The Web API is implemented using the OData v4 standard which uses a specific set of terms you need to be familiar with. Entity Data Model (EDM) is the abstract data model that is used to describe the data exposed by an OData service. The following table is a selected list of terms defined in OData Version 4.0 Part 1: Protocol Plus Errata 02 which you should understand.
Term | Definition |
---|---|
Entity types | Named structured types with a key. They define the named properties and relationships of an entity. Entity types may derive by single inheritance from other entity types. |
Entities | Instances of entity types (e.g. account, opportunity). |
Entity sets | Named collections of entities (e.g. accounts is an entity set containing account entities). An entity's key uniquely identifies the entity within an entity set |
Complex types | Keyless named structured types consisting of a set of properties. Complex types are commonly used as property values in model entities, or as parameters or return values for operations. |
Enumeration types or Enum types | Named primitive types whose values are named constants with underlying integer values. |
Functions | Operations that do not have side effects and may support further composition, for example, with additional filter operations, functions or an action |
Actions | Operations that allow side effects, such as data modification, and cannot be further composed in order to avoid non-deterministic behavior |
Service documents
There are two service documents you can reference to learn more about the Web API.
Service document
The following query, typed into the address field of your browser, returns the service document, a complete list of all the entity sets that are available for your organization. Note that [organization URI] represents the URL for your organization.
[Organization URI]/api/data/v9.0
The entity sets are returned in the form of a JSON array. Each item in the array has three properties as listed in this table.
Property | Description |
---|---|
name |
This is the name of the entity set. This data is from the EntityMetadata EntityType EntitySetName property for the entity. |
kind |
For the web API only Entity sets are listed. |
url |
This value is the same as the name property and it represents the part of the resource path to retrieve data for the entity. |
This information can be retrieved using a GET
request and may be useful to get a list of all entity sets available using the service.
CSDL $metadata document
A GET
request to the following URL will return a rather large (more than 3.5 MB) Common Schema Definition Language (CSDL) document, or metadata document that describes the data and operations exposed by the service.
GET [Organization URI]/api/data/v9.0/$metadata
This document can be used as a data source to generate classes that will provide strongly typed objects for the service. But if you are not using generated classes, you may want to review documentation generated from this information instead. The Web API Reference uses information primarily from this document taken from a system with common additional solutions installed.
You can learn more about this document in OData Version 4.0 Part 3: Common Schema Definition Language (CSDL) Plus Errata 02.
Tip
Before your read the rest of this topic, download the $metadata
for your organization and take a look at how the types, functions, and actions described are included in the $metadata
and the supporting documentation.
You can view or download the document using your browser by navigating to the URL.
Metadata annotations
The metadata document includes several types of Annotation
elements which provide additional information about metadata elements and the capabilities of the service. Starting with v9.x, these annotations are not included with the default metadata document unless explicitly requested. These annotations increase the size of the metadata document and are not always necessary.
To include annotations you have two options when requesting the metadata document:
Append the
?annotations=true
query string parameter to the URL.Add the
Prefer: odata.include-annotations="*"
header to the request.
Each Annotation
element includes a Term
attribute that describes the type of annotation. The definitions of all the possible annotations used by OData v4 can be found in OData Vocabularies Version 4.0. The following table provides some examples used by the Web API.
Term | Description |
---|---|
Org.OData.Core.V1.Description |
A description of an entitytype or property. |
Org.OData.Core.V1.Permissions |
A list of permissions available for a property when permissions are restricted. Typically this will appear for properties with only a single <EnumMember>Org.OData.Core.V1.PermissionType/Read</EnumMember> child element to indicate that the property is read-only. |
Org.OData.Core.V1.Computed |
Whether the property is computed. These are also usually read-only. |
OData.Community.Keys.V1.AlternateKeys |
Contains a collection of elements that describe any alternate keys defined for an entity. More information:Alternate keys |
Org.OData.Capabilities.V1.IndexableByKey |
Whether an entityset supports key values according to OData URL conventions. |
Org.OData.Capabilities.V1.SkipSupported |
Whether an entityset supports $skip . |
Org.OData.Capabilities.V1.SearchRestrictions |
What kinds of restrictions on $search expressions are applied to an entityset. |
Org.OData.Capabilities.V1.CountRestrictions |
What kinds of restrictions on /$count path suffix and $count=true system query option. |
Org.OData.Capabilities.V1.NavigationRestrictions |
What kinds of restrictions on navigating properties according to OData URL conventions. |
Org.OData.Capabilities.V1.ChangeTracking |
The change tracking capabilities of this service or entity set. |
Org.OData.Capabilities.V1.ConformanceLevel |
The conformance level achieved by this service. |
Org.OData.Capabilities.V1.FilterFunctions |
A list of functions and operators supported in $filter . |
Org.OData.Core.V1.DereferenceableIDs |
Whether Entity-ids are URLs that locate the identified entity. |
Org.OData.Core.V1.ConventionalIDs |
Whether Entity-ids follow OData URL conventions. |
Org.OData.Capabilities.V1.AsynchronousRequestsSupported |
Whether the service supports the asynchronous request preference. |
Org.OData.Capabilities.V1.BatchContinueOnErrorSupported |
Whether the service supports the continue on error preference. This setting supports $batch requests. |
Org.OData.Capabilities.V1.CrossJoinSupported |
Whether cross joins for the entity sets in this container are supported. |
Org.OData.Capabilities.V1.SupportedFormats |
The media types of supported formats, including format parameters. |
Entity types
The Web API EntityType Reference lists each of the system entity types exposed through the web API which store business data. An entity type is a named structured type with a key. It defines the named properties and relationships of an entity. Entity types may derive by single inheritance from other entity types. Web API Metadata EntityType Reference lists each of the entity types used to manage system metadata. Both are entity types but the way you work with them is different. See Use the Web API with Microsoft Dataverse metadata for information about using model entities. Each entity type is included within an EntityType
element in the $metadata
. The following is the definition of the account EntityType from the $metadata
with properties and navigation properties removed.
<EntityType Name="account" BaseType="mscrm.crmbaseentity">
<Key>
<PropertyRef Name="accountid" />
</Key>
<!--Properties and navigation properties removed for brevity-->
<Annotation Term="Org.OData.Core.V1.Description" String="Business that represents a customer or potential customer. The company that is billed in business transactions." />
</EntityType>
Each EntityType
reference page in the SDK documentation uses information from the $metadata
to show the following information when available.
Information | Description |
---|---|
Description | A description of the entity. The EntityMetadata EntityType Description property information is included in the EntityType element using the Annotation element with the Term attribute value of Org.OData.Core.V1.Description. |
Collection URL | The URL to access the collection of each type. The EntityMetadata EntityType EntitySetName property information is included using the $metadata EntityContainer element. The Name attribute of each EntitySet element controls how the data is accessed via the URL. |
Base Type | This is the entity type that the entity type inherits from. The BaseType attribute of the EntityType element contains the name of the entity type. This name is prefixed with the alias for the Microsoft.Dynamics.CRM namespace: mscrm. More information:Type inheritance |
Display Name | This information is not in the $metadata , it’s retrieved from the EntityMetadata EntityType DisplayName property. |
Primary Key | The property value that contains the unique identifier to refer to an instance of an entity. The EntityMetadata EntityType PrimaryIdAttribute property value is included in the EntityType Key element. Each entity can have just one primary key.Alternate keys are not listed here. More information:Alternate keys |
Primary Attribute | Many entities require that a primary attribute value be set, so this is included for convenience. This information is not in the $metadata , it’s retrieved from the metadata EntityMetadata EntityType PrimaryNameAttribute property. |
Properties | See Properties. |
Single-valued navigation properties | See Single-Valued navigation properties. |
Collection-valued navigation properties | See Collection-valued navigation properties. |
Operations bound to the entity type | When an operation is bound to a specific entity type, it’s listed for convenience. |
Operations that use the entity type | This list shows any operations that may use the entity type. This is derived by collecting references to all operations that refer to the current type in the parameters or as a return value. |
Entity types that inherit from the entity type | This list includes any entity types that inherit directly from the entity type. See Type inheritance for more information. |
Change the name of an entity set
By default, the entity set name matches the EntityMetadata EntityType LogicalCollectionName
(EntityMetadataLogicalCollectionName
) property value. If you have a custom entity that you want to address using a different entity set name, you can update the EntityMetadata EntityType EntitySetName
(EntityMetadata.EntitySetName
) property value to use a different name.
Alternate keys
Although Dataverse allows for creating alternate keys, only the primary key will be found in the default entities.
None of the system entities have alternate keys defined. If you define alternate keys for an entity, they will be included in the $metadata
EntityType
element as an Annotation
like the following:
<Annotation Term="OData.Community.Keys.V1.AlternateKeys">
<Collection>
<Record Type="OData.Community.Keys.V1.AlternateKey">
<PropertyValue Property="Key">
<Collection>
<Record Type="OData.Community.Keys.V1.PropertyRef">
<PropertyValue Property="Alias" String="key name" />
<PropertyValue Property="Name" PropertyPath="key name" />
</Record>
</Collection>
</PropertyValue>
</Record>
</Collection>
</Annotation>
Information about alternate keys can also be retrieved from the metadata using the EntityMetadata EntityType Keys
collection-valued navigation property using the Web API or the EntityMetadata.Keys
property using the organization service.
Type inheritance
Inheritance allows for sharing of common properties and categorizing entity types into groups. All entity types in the web API inherit from two of the following entity types. All business entity types inherit from the crmbaseentity EntityType and all model entities inherit from the crmmodelbaseentity EntityType.
Base entity | Description |
---|---|
crmbaseentity EntityType | All business entities inherit from this entity. It has no properties. It only serves as an abstract base entity. |
activitypointer EntityType | All activity entities inherit from this entity. It defines the common set of properties and navigation properties for activity entities. |
principal EntityType | The systemuser EntityType and team EntityType inherit a common ownerid property from this entity. |
crmmodelbaseentity EntityType | Only MetadataBase EntityType inherits directly from this entity. It has no properties. It only serves as an abstract base entity. |
MetadataBase EntityType) | All metadata entities inherit from this entity. It provides the MetadataId and HasChanged properties for all metadata entities. |
AttributeMetadata EntityType | All model entities that represent different types of attributes inherit from this entity. |
EnumAttributeMetadata EntityType | Those model entities that represent attributes that include a set of options inherit from this entity. |
OptionSetMetadataBase EntityType | This model entity type provides a common set of properties used by the BooleanOptionSetMetadata EntityType and OptionSetMetadata EntityType model entity types that inherit from it. |
RelationshipMetadataBase EntityType | This entity type provides a common set of properties used by the ManyToManyRelationshipMetadata EntityType and OneToManyRelationshipMetadata EntityType model entity types that inherit from it. |
Properties
Each entity type may have declared properties that correspond to attributes. In the Web API EntityType Reference and Web API Metadata EntityType Reference content, properties that are inherited from a base entity type are combined within the list of declared properties for each entity type. The inheritance is called out in the description for each property.
In the $metadata
EntityType
elements each property is included in a Property
element with a Name
attribute value that corresponds to the properties you will set in code. The Type
attribute value specifies the data type of the property. Properties for business entity types generally use OData primitive types.
The following is an example of the account EntityType name
property defined in the $metadata
.
<Property Name="name" Type="Edm.String" Unicode="false">
<Annotation Term="Org.OData.Core.V1.Description" String="Type the company or business name." />
</Property>
The description of the property is available in an Annotation
element with the Term
attribute property of Org.OData.Core.V1.Description. This description is taken from the AttributeMetadata EntityType Description
property value. Not all properties have a description.
Each property may be computed. This means that the value may be set by the system. This is specified in an Annotation
element with the Term
attribute value of Org.OData.Core.V1.Computed.
Each property may also have limitations on whether it may be updated. This is defined in an Annotation
element with a Term
attribute value Org.OData.Core.V1.Permissions. The only option set for this is Org.OData.Core.V1.PermissionType/Read, which indicates that the property is read only.
Primitive types
OData supports a wide range of data types but Dataverse doesn’t use all of them. The following table describes how Dataverse Organization service types are mapped to OData primitive types.
Organization Service Type | Web API Type | Description |
---|---|---|
BigInt | Edm.Int64 | Signed 64-bit integer |
Boolean | Edm.Boolean | Binary-valued logic |
CalendarRules | Single-valued navigation properties | Specific single-valued navigation properties to the calendarrule EntityType. |
Customer | Single-valued navigation properties | The customer of an entity with this type of property may be a single-valued navigation property set to either an account or contact entity type using the respective single-valued navigation properties. When either of the respective single-valued collection properties is set, the other is cleared. |
DateTime | Edm.DateTimeOffset | Date and time with a time-zone offset, no leap seconds There is no DateTime type in OData. |
Decimal | Edm.Decimal | Numeric values with fixed precision and scale |
Double | Edm.Double | IEEE 754 binary64 floating-point number (15-17 decimal digits) |
EntityName | Edm.String | Sequence of UTF-8 characters |
Image | Edm.Binary | Binary data |
Integer | Edm.Int32 | Signed 32-bit integer |
Lookup | Single-valued navigation property | A reference to a specific entity |
ManagedProperty | Not applicable | For internal use only. |
Memo | Edm.String | Sequence of UTF-8 characters |
Money | Edm.Decimal | Numeric values with fixed precision and scale |
Owner | Single-valued navigation property | A reference to the principal EntityType. Both systemuser and team entity types inherit their ownerid property from the principal entity type. |
Picklist | Edm.Int32 | Signed 32-bit integer |
State | Edm.Int32 | Signed 32-bit integer |
Status | Edm.Int32 | Signed 32-bit integer |
String | Edm.String | Sequence of UTF-8 characters |
Uniqueidentifier | Edm.Guid | 16-byte (128-bit) unique identifier |
Lookup properties
For most single-valued navigation properties you will find a computed, read-only property that uses the following naming convention: _<name>_value
where the <name>
matches the name of the single-valued navigation property. The exception to this pattern is when a lookup attribute of the entity can accept multiple types of entity references. A common example is how the incident
entity customerid
attribute may be set to a reference that is either a contact
or account
entity. In the incident EntityType Single-valued navigation properties you will find customerid_account
and customerid_contact
as separate single-valued navigation properties to reflect the customer associated with an opportunity. If you set one of these single-valued navigation properties, the other will be set to null because they are both bound to the customerid
attribute. In the incident EntityType Properties you’ll find a _customerid_value
lookup property that contains the same value that is set for whichever of the single-valued navigation properties contain a value.
Generally, you should avoid using lookup properties and use the corresponding single-valued navigation properties instead. These properties have been included because they may be useful for certain integration scenarios. These properties are read-only and computed because they will simply reflect the changes applied using the corresponding single-valued navigation property.
When you include lookup properties in a query, you can request annotations to be included that provide additional information about the data that is set for those underlying attributes which aren’t represented by a single-valued navigation property. More information:Retrieve data about lookup properties
Navigation properties
In OData, navigation properties allow you to access data related to the current entity. When you retrieve an entity you can choose to expand navigation properties to include the related data. There are two types of navigation properties: single-valued and collection-valued.
Single-valued navigation properties
These properties correspond to Lookup attributes that support many-to-one relationships and allow setting a reference to another entity. In the $metadata
EntityType
element, these are defined as a NavigationProperty
element with at Type
attribute set to a single type. The following is an example of the account EntityType createdby
single-valued navigation property in the $metadata
:
<NavigationProperty Name="createdby" Type="mscrm.systemuser" Nullable="false" Partner="lk_accountbase_createdby">
<ReferentialConstraint Property="_createdby_value" ReferencedProperty="systemuserid" />
</NavigationProperty>
Every navigation property that represents a single-valued navigation property will have a corresponding collection-valued navigation property indicated by the Partner
attribute value. Each single-valued navigation property also has a ReferentialConstraint
element with Property
attribute value that represents the computed read-only lookup property that can be used to retrieve corresponding GUID value of the related entity. More information:Lookup properties
Collection-valued navigation properties
These properties correspond to one-to-many or many-to-many relationships. In the $metadata
EntityType
element, these are defined as a NavigationProperty
element with at Type
attribute set to a collection of a type. The following represents the account EntityType Account_Tasks
collection-valued navigation property which represents a one-to-many relationship:
<NavigationProperty Name="Account_Tasks" Type="Collection(mscrm.task)" Partner="regardingobjectid_account_task" />
When the collection-valued navigation property represents a many-to-many relationship, the name of the navigation property and the name of the partner will be the same. The following represents the account EntityType accountleads_association
collection-valued navigation property which represents a many-to-many relationship:
<NavigationProperty Name="accountleads_association" Type="Collection(mscrm.lead)" Partner="accountleads_association" />
The difference between one-to-many and many-to-many relationships is not important when using the Web API. The way you associate entities is the same regardless of the type of relationship. Although many-to-many relationships still use intersect entities behind the scenes, only a few special system intersect entities are included within the Web API EntityType Reference. For example, campaignactivityitem EntityType is technically an intersect entity, but it is included because it has more properties than an ordinary intersect entity.
An ordinary intersect entity has only the four basic properties required to maintain the many-to-many relationship. When you create a custom many-to-many relationship between entities, an ordinary intersect entity will be created to support the relationship. Because you should use navigation properties to perform operations involving many-to-many relationships, ordinary intersect entities are not documented but are still available using the Web API. These intersect entity types are accessible using an entity set name that uses the following naming convention: <intersect entity logical name>+’collection’. For example, you can retrieve information from the contactleads intersect entity type using [Organization URI]/api/data/v9.0/contactleadscollection
. You should only use these ordinary intersect entities in situations where you wish to apply change tracking.
Actions
Actions are operations that allow side effects, such as data modification, and cannot be further composed in order to avoid non-deterministic behavior.
The Web API Action Reference topic lists each of the available system actions. More information:Use Web API actions.
Functions
Functions are operations that do not have side effects and may support further composition, for example, with additional filter operations, functions or an action
There are two types of functions defined in the Web API:
The Web API Function Reference lists each of the available system functions.
The Web API Query Function Reference topic lists functions which are intended to be used as criteria in a query.
More information:Use Web API functions
Complex types
Complex types are keyless named structured types consisting of a set of properties. Complex types are commonly used as property values in model entities, or as parameters or return values for operations.
Web API ComplexType Reference lists all the system complex types. The following is the WhoAmIResponse ComplexType from the $metadata.
<ComplexType Name="WhoAmIResponse">
<Property Name="BusinessUnitId" Type="Edm.Guid" Nullable="false" />
<Property Name="UserId" Type="Edm.Guid" Nullable="false" />
<Property Name="OrganizationId" Type="Edm.Guid" Nullable="false" />
</ComplexType>
Enumeration types
Enumeration types or EnumTypes are named primitive types whose values are named constants with underlying integer values.
Web API EnumType Reference lists all the system enumeration types. Enumeration types are named primitive types whose values are named constants with underlying integer values. The following is the AccessRights EnumType from the $metadata.
<EnumType Name="AccessRights">
<Member Name="None" Value="0" />
<Member Name="ReadAccess" Value="1" />
<Member Name="WriteAccess" Value="2" />
<Member Name="AppendAccess" Value="4" />
<Member Name="AppendToAccess" Value="16" />
<Member Name="CreateAccess" Value="32" />
<Member Name="DeleteAccess" Value="65536" />
<Member Name="ShareAccess" Value="262144" />
<Member Name="AssignAccess" Value="524288" />
</EnumType>
See also
Use the Dataverse Web API
Authenticate to Dataverse with the Web API
Perform operations using the Web API
Note
Can you tell us about your documentation language preferences? Take a short survey.
The survey will take about seven minutes. No personal data is collected (privacy statement).