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
- Read relationship metadata to identify the navigation property and target entity set.
- Use POST to the collection-valued navigation property followed by /$ref to associate an existing row.
- Use DELETE on the navigation property’s $ref URL with the target row reference to remove the link.
- Use the correct single-valued navigation property for supported one-to-many relationships and verify the relationship direction.
- 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.