Associate and disassociate entities using the Web API

Dynamics CRM 2016
 

Updated: November 29, 2016

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

There are several methods you can use to associate and disassociate entities. Which method you apply depends on whether you’re creating or updating the entities and whether you’re operating in the context of the referenced entity or the referencing entity.

The following example shows how to associate an existing opportunity entity with the opportunityid value of 00000000-0000-0000-0000-000000000001 to the collection-valued opportunity_customer_accounts navigation property for an account entity with the accountid value of 00000000-0000-0000-0000-000000000002. This is a 1:N relationship but you can perform the same operation for an N:N relationship.

Request
POST [Organization URI]/api/data/v8.2/accounts(00000000-0000-0000-0000-000000000002)/opportunity_customer_accounts/$ref HTTP/1.1 
Content-Type: application/json 
Accept: application/json 
OData-MaxVersion: 4.0 
OData-Version: 4.0

{
"@odata.id":"[Organization URI]/api/data/v8.2/opportunities(00000000-0000-0000-0000-000000000001)"
}
Response
HTTP/1.1 204 No Content
OData-Version: 4.0

Use a DELETE request to remove a reference to an entity. The way you do it is different depending on whether you’re referring to a collection-valued navigation property or a single-valued navigation property.

Request

For a collection-valued navigation property, use the following.

DELETE [Organization URI]/api/data/v8.2/accounts(00000000-0000-0000-0000-000000000002)/opportunity_customer_accounts/$ref?$id=[Organization URI]/api/data/v8.2/opportunities(00000000-0000-0000-0000-000000000001) HTTP/1.1
Accept: application/json
OData-MaxVersion: 4.0
OData-Version: 4.0

Or, use this.

DELETE [Organization URI]/api/data/v8.2/accounts(00000000-0000-0000-0000-000000000002)/opportunity_customer_accounts(00000000-0000-0000-0000-000000000001)/$ref HTTP/1.1
Accept: application/json
OData-MaxVersion: 4.0
OData-Version: 4.0
Request

For a single-valued navigation property, remove the $id query string parameter.

DELETE [Organization URI]/api/data/v8.2/opportunities(00000000-0000-0000-0000-000000000001)/customerid_account/$ref HTTP/1.1
Accept: application/json
OData-MaxVersion: 4.0
OData-Version: 4.0
Response

Either way, a successful response has status 204.

HTTP/1.1 204 No Content
OData-Version: 4.0

You can associate entities by setting the value of a single-valued navigation property using PUT request with the following pattern.

Request
PUT [Organization URI]/api/data/v8.2/opportunities(00000000-0000-0000-0000-000000000001)/customerid_account/$ref HTTP/1.1
Content-Type: application/json
Accept: application/json
OData-MaxVersion: 4.0
OData-Version: 4.0

{
 "@odata.id":"[Organization URI]/api/data/v8.2/accounts(00000000-0000-0000-0000-000000000002)"
}
Response
HTTP/1.1 204 No Content
OData-Version: 4.0

As described in Create related entities in one operation, new entities can be created with relationships using deep insert.

You can associate entities on update using the same message described in Basic update but you must use the @odata.bind annotation to set the value of a single-valued navigation property. The following example changes the account associated to an opportunity using the customerid_account single-valued navigation property.

Request
PATCH [Organization URI]/api/data/v8.2/opportunities(00000000-0000-0000-0000-000000000001) HTTP/1.1
Content-Type: application/json
Accept: application/json
OData-MaxVersion: 4.0
OData-Version: 4.0

{
 "customerid_account@odata.bind":"[Organization URI]/api/data/v8.2/accounts(00000000-0000-0000-0000-000000000002)"
}
Response
HTTP/1.1 204 No Content
OData-Version: 4.0

Microsoft Dynamics 365

© 2016 Microsoft. All rights reserved. Copyright

Community Additions

ADD
Show: