Dataverse Web API Associate and Disassociate: Link Existing Records

The Web API represents relationship changes through navigation properties and the $ref endpoint. This lets an integration link existing records without recreating them or changing unrelated attributes.

Concept and use case

Use Dataverse Web API $ref endpoints to associate and disassociate existing records across one-to-many and many-to-many relationships.

Implementation steps

  1. Read relationship metadata to identify the navigation property and target entity set.
  2. Use POST to the collection-valued navigation property followed by /$ref to associate an existing row.
  3. Use DELETE on the navigation property’s $ref URL with the target row reference to remove the link.
  4. Use the correct single-valued navigation property for supported one-to-many relationships and verify the relationship direction.
  5. Check Append and Append To privileges on the involved tables and test with the intended integration identity.

Request or configuration example

// Associate a contact with an account through a collection navigation property
POST https://<org>.crm.dynamics.com/api/data/v9.2/accounts(<account-id>)/contact_customer_accounts/$ref
Content-Type: application/json

{"@odata.id":"https://<org>.crm.dynamics.com/api/data/v9.2/contacts(<contact-id>)"}

Common pitfalls

  • Do not guess the navigation property name from the lookup column label.
  • Do not overlook Append and Append To privileges.
  • Ensure the request references an existing row in the correct entity set.

Testing checklist

Test associate and disassociate, repeat the request, verify relationship direction and confirm insufficient privileges return a clear error.

Conclusion

Choose the platform feature that matches the integration contract, keep payloads explicit and validate both success and failure responses before production rollout.