Summary
We are deprecating the mergeOperation field, which is set via the deprecated POST /api/v2/externalcontacts/merge/contacts. This is a readOnly field, but it is returned by any External Contact API that returns data on external contact(s). This field can be used to indicate if a contact was part of a merge operation using the deprecated merge API. This field can only represent 2-way merges, and cannot represent n-way merging.
This field is being replaced by the mergedTo, mergedFrom and canonicalContact fields, which are all set in the new POST /api/v2/externalcontacts/contacts/merge API.
Effective Date
Monday, July 21, 2025
Details
The introduction of the new v2 merge API (POST /api/v2/externalcontacts/contacts/merge) enables support for N-way merging. As the mergeOperation field is restricted to two-way merges, users are advised to transition to using the mergedTo, mergedFrom, and canonicalContact fields. These new fields can accurately represent both two-way and N-way merges, ensuring consistency across merge APIs and mitigating potential confusion.
Customer Impact
Users who currently rely on the mergeOperation value in API responses will need to update their implementations to use the mergedTo, mergedFrom, and canonicalContact values instead.
Furthermore, users are encouraged to adopt the POST /api/v2/externalcontacts/contacts/merge API for all future merging operations.
Impacted Resources
POST /api/v2/externalcontacts/merge/contacts
Issue References
[RELATE-16616]
Contacts
@Joyanne Njuguna @Colin Reilly
Please reply to this announcement with any questions. This helps the wider developer community benefit from the discussion. We encourage you to use this thread before contacting the designated person directly. Thank you for your understanding.