Create and update entity relationships using the Web API

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

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 Entity relationship metadata

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/v9.0/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/v9.0/RelationshipDefinitions(d475020f-5d7c-e511-80d2-00155d2a68d2)  

Create a many-to-many relationship

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/v9.0/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/v9.0/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.

See also

Use the Web API with Common Data Service metadata
Query Metadata using the Web API
Retrieve metadata by name or MetadataId
Model entites and attributes using the Web API