Create and update entity relationships using the Web API

Article
11/28/2016

Applies To: Dynamics 365 (online), Dynamics 365 (on-premises), Dynamics CRM 2016, Dynamics CRM Online

The Web API supports working with relationship metadata. The concepts described in Customize entity relationship metadata also apply to the Web API.

In this topic

Eligibility for relationships

Create a one-to-many relationship

Create a many-to-many relationship

Update Relationships

Delete Relationships

Eligibility for relationships

Before you create an entity relationship you should confirm whether the entity is eligible to participate in the relationship. You can use the actions listed in the following table to determine eligibility. These actions correspond to the organization service messages described in Entity relationship eligibility.

Action	Description
CanBeReferenced Action	Checks whether the specified entity can be the primary entity (one) in a one-to-many relationship.
CanBeReferencing Action	Checks whether the specified entity can be the referencing entity (many) in a one-to-many relationship.
CanManyToMany Action	Checks whether the entity can participate in a many-to-many relationship.
GetValidManyToMany Function	Returns the set of entities that can participate in a many-to-many relationship.
GetValidReferencedEntities Function	Returns the set of entities that are valid as the primary entity (one) from the specified entity in a one-to-many relationship.
GetValidReferencingEntities Function	Returns the set of entities that are valid as the related entity (many) to the specified entity in a one-to-many relationship.

Create a one-to-many relationship

When you create a one-to-many relationship, you define it by using the OneToManyRelationshipMetadata EntityType. This definition includes the lookup attribute, which is defined by using LookupAttributeMetadata EntityType and also requires complex properties using AssociatedMenuConfiguration ComplexType, CascadeConfiguration ComplexType, Label ComplexType and LocalizedLabel ComplexType. The lookup attribute is set to the Lookup single-valued navigation property of the OneToManyRelationshipMetadata object and gets created at the same time using deep insert. More information: Create related entities in one operation and One-to-many relationships

If you want to apply a custom navigation property name for a one-to-many relationship you can set values for the ReferencingEntityNavigationPropertyName and ReferencedEntityNavigationPropertyName properties.

Once you have generated the necessary JSON to define the relationship and the lookup attribute, POST the JSON to the RelationshipDefinitions entity set. You must include the @odata.type property value of Microsoft.Dynamics.CRM.OneToManyRelationshipMetadata to clarify the type of relationship you’re creating because this same entity set is used to create many-to-many relationships. The uri for the resulting relationship is returned in the response.

Request

POST [Organization URI]/api/data/v8.2/RelationshipDefinitions HTTP/1.1
Accept: application/json
Content-Type: application/json; charset=utf-8
OData-MaxVersion: 4.0
OData-Version: 4.0

{
 "SchemaName": "new_contact_new_bankaccount",
 "@odata.type": "Microsoft.Dynamics.CRM.OneToManyRelationshipMetadata",
 "AssociatedMenuConfiguration": {
  "Behavior": "UseCollectionName",
  "Group": "Details",
  "Label": {
   "@odata.type": "Microsoft.Dynamics.CRM.Label",
   "LocalizedLabels": [
    {
     "@odata.type": "Microsoft.Dynamics.CRM.LocalizedLabel",
     "Label": "Bank Accounts",
     "LanguageCode": 1033
    }
   ],
   "UserLocalizedLabel": {
    "@odata.type": "Microsoft.Dynamics.CRM.LocalizedLabel",
    "Label": "Bank Accounts",
    "LanguageCode": 1033
   }
  },
  "Order": 10000
 },
 "CascadeConfiguration": {
  "Assign": "Cascade",
  "Delete": "Cascade",
  "Merge": "Cascade",
  "Reparent": "Cascade",
  "Share": "Cascade",
  "Unshare": "Cascade"
 },
 "ReferencedAttribute": "contactid",
 "ReferencedEntity": "contact",
 "ReferencingEntity": "new_bankaccount",
 "Lookup": {
  "AttributeType": "Lookup",
  "AttributeTypeName": {
   "Value": "LookupType"
  },
  "Description": {
   "@odata.type": "Microsoft.Dynamics.CRM.Label",
   "LocalizedLabels": [
    {
     "@odata.type": "Microsoft.Dynamics.CRM.LocalizedLabel",
     "Label": "The owner of the account",
     "LanguageCode": 1033
    }
   ],
   "UserLocalizedLabel": {
    "@odata.type": "Microsoft.Dynamics.CRM.LocalizedLabel",
    "Label": "The owner of the account",
    "LanguageCode": 1033
   }
  },
  "DisplayName": {
   "@odata.type": "Microsoft.Dynamics.CRM.Label",
   "LocalizedLabels": [
    {
     "@odata.type": "Microsoft.Dynamics.CRM.LocalizedLabel",
     "Label": "Account Owner",
     "LanguageCode": 1033
    }
   ],
   "UserLocalizedLabel": {
    "@odata.type": "Microsoft.Dynamics.CRM.LocalizedLabel",
    "Label": "Account Owner",
    "LanguageCode": 1033
   }
  },
  "RequiredLevel": {
   "Value": "ApplicationRequired",
   "CanBeChanged": true,
   "ManagedPropertyLogicalName": "canmodifyrequirementlevelsettings"
  },
  "SchemaName": "new_AccountOwner",
  "@odata.type": "Microsoft.Dynamics.CRM.LookupAttributeMetadata"
 }
}

Response

HTTP/1.1 204 No Content
OData-Version: 4.0
OData-EntityId: [Organization URI]/api/data/v8.2/RelationshipDefinitions(d475020f-5d7c-e511-80d2-00155d2a68d2)

Create a many-to-many relationship

When you create a many-to-many relationship, you must the relationship by using the ManyToManyRelationshipMetadata EntityType. This definition includes the name of the intersect entity to be created as well as how the relationship should be displayed in the application by using AssociatedMenuConfiguration ComplexType, Label ComplexType and LocalizedLabel ComplexType. More information: Many-to-many relationships

If you want to apply a custom navigation property name for a many-to-many relationship, you can set values for the Entity1NavigationPropertyName and Entity2NavigationPropertyName properties.

Once you have generated the necessary JSON to define the relationship, POST the JSON to the RelationshipDefinitions entity set. You must include the @odata.type property value of Microsoft.Dynamics.CRM.ManyToManyRelationshipMetadata to clarify the type of relationship you’re creating because this same entity set is used to create one-to-many relationships. The uri for the resulting relationship is returned in the response.

Request

POST [Organization URI]/api/data/v8.2/RelationshipDefinitions HTTP/1.1
Accept: application/json
Content-Type: application/json; charset=utf-8
OData-MaxVersion: 4.0
OData-Version: 4.0

{
 "SchemaName": "new_accounts_campaigns",
 "@odata.type": "Microsoft.Dynamics.CRM.ManyToManyRelationshipMetadata",
 "Entity1AssociatedMenuConfiguration": {
  "Behavior": "UseLabel",
  "Group": "Details",
  "Label": {
   "@odata.type": "Microsoft.Dynamics.CRM.Label",
   "LocalizedLabels": [
    {
     "@odata.type": "Microsoft.Dynamics.CRM.LocalizedLabel",
     "Label": "Account",
     "LanguageCode": 1033
    }
   ],
   "UserLocalizedLabel": {
    "@odata.type": "Microsoft.Dynamics.CRM.LocalizedLabel",
    "Label": "Account",
    "LanguageCode": 1033
   }
  },
  "Order": 10000
 },
 "Entity1LogicalName": "account",
 "Entity2AssociatedMenuConfiguration": {
  "Behavior": "UseLabel",
  "Group": "Details",
  "Label": {
   "@odata.type": "Microsoft.Dynamics.CRM.Label",
   "LocalizedLabels": [
    {
     "@odata.type": "Microsoft.Dynamics.CRM.LocalizedLabel",
     "Label": "Campaign",
     "LanguageCode": 1033
    }
   ],
   "UserLocalizedLabel": {
    "@odata.type": "Microsoft.Dynamics.CRM.LocalizedLabel",
    "Label": "Campaign",
    "LanguageCode": 1033
   }
  },
  "Order": 10000
 },
 "Entity2LogicalName": "campaign",
 "IntersectEntityName": "new_accounts_campaigns"
}

Response

HTTP/1.1 204 No Content
OData-Version: 4.0
OData-EntityId: [Organization URI]/api/data/v8.2/RelationshipDefinitions(420245fa-c77c-e511-80d2-00155d2a68d2)

Update Relationships

As discussed in Update entities, you update relationships using the HTTP PUT method to replace the existing definition with changes you want to apply. You can’t edit individual properties using the HTTP PATCH method as you can with business data entities. Just like with entities and attributes, you should include a MSCRM.MergeLabels header with the value set to true to avoid overwriting localized labels not included in your update and you must publish customizations before they are active in the system.

Delete Relationships

To delete a relationship using the Web API, use the HTTP DELETE method with the URI for the relationship.

Share via

Create and update entity relationships using the Web API

In this topic

Eligibility for relationships

Create a one-to-many relationship

Create a many-to-many relationship

Update Relationships

Delete Relationships

See Also

Additional resources