In May 2023, the rules for merging two persons were changed. The change was made on the server side and there is no need for users to upgrade their SDK.
This article explains the new rules for merging to help users troubleshoot any potential issues more easily.


In every merge operation, there are two persons (two FIFA_IDs) involved: PRIMARY and SECONDARY. The FIFA_ID passed to a Merge(...) method as SECONDARY will become "inactive" meaning the record will no longer be available. Any client trying to execute any operation on the SECONDARY merged record, will receive a 301 ("Person merged") error. One reason for introducing Notifications (you can find more here: Connect ID Notifications) was to inform the data holders of the SECONDARY merged FIFA_ID so that they know that they should replace their FIFA_ID. FIFA_ID passed as PRIMARY will continue to exist without any changes.


When is it allowed to merge two persons?

The simplest way to explain the rule is as follows: you can merge if you have any registration for a given record and your registration is equal to or higher-ranked (in terms of the status, so "active" > "pending" > "inactive") than other MA's registration for a SECONDARY record. 


In practice, you will be able to merge SECONDARY record into PRIMARY record if:

  1. either you're the only MA to have any SECONDARY registration
  2. or you have an "active" SECONDARY registration
  3. or you have a "pending" SECONDARY registration and all other SECONDARY registrations have "pending" or "inactive" status only (PRIMARY registrations may be active, pending or inactive)
  4. or you have an "inactive" SECONDARY registration and all other SECONDARY registrations have "inactive" status only (PRIMARY registrations may be active, pending or inactive)

 

Even if none of the above conditions is fulfilled, you'll also be able to merge if:

  1. you have an "active" PRIMARY registration
  2. you have a "pending" PRIMARY registration and all other MA's SECONDARY registrations are "pending" or "inactive"
  3. you have an "inactive" PRIMARY registration and all other MAs' SECONDARY registrations are "inactive"


The lack of symmetry in the rules is caused by the fact that the merge is going to "invalidate" the SECONDARY FIFA_ID, requiring other MAs to replace their FIFA_IDs. At the same time any PRIMARY MAs will not be affected at all.


When is it NOT allowed to merge two persons?

You will not be able to merge a SECONDARY record into a PRIMARY record if:

  1. either you don't have any registration for any of the records, regardless of the registration status.
  2. or your registration for a SECONDARY record is lower-ranked than a registration of another MA for a SECONDARY record
    1. your registration is "inactive" while the other registration is "pending" or "active"
    2. your registration is "pending" while the other registration is "active"
  3. or your registration for a PRIMARY record is lower-ranked than a registration of another MA for a SECONDARY record


Point 1 is easy to explain: if you do not have a stake in any of the persons (i.e. you don't have a registration) you should not be allowed to manage them.


Rule number 2 is caused by the fact, that merging a record as SECONDARY makes it unavailable. Because another MA has a registration, merging causes them some trouble - at least until they act on a notification and replace the FIFA_ID. Hence the rule that only allows you to do it if your registration is equal to or higher-ranked than of the other MA.


Rule number 3 can be explained in the same way as rule number 2. Merges cause some trouble for registration owners of SECONDARY record, so our registration should be equal to or higher-ranked to perform the merge. Let's observe again that the algorithm never compares your registration with PRIMARY registrations. The reason is that owners of PRIMARY registrations are not affected by the merge.


When are the new rules less restrictive than the previous ones? 

In general, the new rules are less restrictive.

We no longer require MA to have an active registration for any of the FIFA_ID. Their registration can be pending or inactive, as long as other MA's secondary registrations are also pending or inactive.

Additionally, the new rule addresses a bug that prevented persons to be merged if any of the registrations was "pending".


When are the new rules more restrictive? 

There is only one such case. Previously you could merge even if you didn't have any registration as long as none of the persons had any active registrations. This is now forbidden.


Error codes/messages

If you are not allowed to merge or unmerge two persons, the operation will fail and throw an exception of type "DataValidationException" with message to aid with troubleshooting. The message will specify which player registrations are missing from either of the players. An example of this message is as follows:

You are not allowed to merge person {SECONDARY_FIFA_ID} (secondary) into {PRIMARY_FIFA_ID} (primary). In order to perform this merge you need to have: either active/pending registration in secondary or either active/pending registration in primary. For more details refer to the documentation.


Ummerge operations

Rules for the unmerge operation are identical.


If you are interested in merges, you may also find the following resources interesting:
What to do if two or more records come up as potential duplicates?
Connect ID Notifications
Merging: how to decide which record is primary?