mergeIdentities

  • Web Services
  • UMPI
  • API Documentation

The mergeIdentities web service is used to force two customer source records (each identified by its Source + Native ID) to be linked together in a common LinkID and convert one of the customer source records into a retired/merged state.

The customer source record converted to a retired/merged state can no longer be updated, but it can still be retrieved with the nativeIdQuery service.

The attribute data from the retired/merged customer source record is also no longer returned as part of the Universal MPI entity to which it is assigned. The data is effectively hidden since the source record has been merged away in the source system.

This service would be used on an exception basis. Typically, it is only used to synchronize a merge action into your Universal MPI instance when a corresponding merge has already been applied to the source system.

Applying mergeIdentities to 2 source records in different LinkIDs

The mergeIdentities service can be applied to two source records that are either already in the same LinkID or are assigned to different LinkIDs.

If the mergeIdentities service is applied to two source records that are in different LinkIDs, the two Universal MPI entities will be combined into a single surviving Universal MPI entity. Any other records that were part of the second LinkID will be combined into the surviving LinkID, but only the single merged-away Source + Native ID will be put into a retired/merged state.

If the overall surviving Universal MPI entity is retrieved in any subsequent web service call, the retired/merged Source + Native ID is returned in the web service response in a separate portion of the JSON object for the identity.

mergeIdentities JSON request

  • The request includes:

    • A tracking ID (an optional identifier that the client can supply to track the response)
    • The Source+Native ID of the customer record that should survive and remain active.
    • The Source+Native ID of the second customer record that should be retired and merged-away – the previously assigned LinkID for this second customer record is retired, and all the source records previously associated with this LinkID are moved into the surviving LinkID
  • {
      "trackingId": "string", 
        "content": 
          { "toSurviveSource": { 
            "name": "string", 
            "id": "string" 
          }, 
            "toRetireSource": { 
            "name": "string", 
            "id": "string" 
        } 
      } 
    }

mergeIdentities JSON response

  • The response includes:

    • An ‘echo’ of the same tracking ID from the request
    • Several Boolean and string values with more information about the success/failure of the service (see section 3.1 above for more information)
    • The LinkID of the single surviving Universal MPI entity
    • The Source+Native ID value for the surviving source record.
  • { 
      "trackingId": "string", 
      "auditId": UUID, 
      "success":  boolean , 
      "retryableError":  boolean , 
      "message": "string", 
      "errors": [ 
        "string" 
      ], 
      "content": {
        "linkId": "string", 
        "toSurviveSource": { 
          "name": "string", 
          "id": "string" 
        } 
      } 
    } 
    

After a source record is merged, most of its data is hidden from view when the entity (LinkID) to which it belongs is subsequently retrieved. The attribute data from that retired source record is hidden, and the retired Source + Native ID is returned in a separate ‘retired sources’ section of JSON.

mergeIdentities example 1

The following example illustrates the behavior. Suppose that prior to a mergeIdentities operation, a single LinkID contained two source record’s worth of information (Source=CRM, Native ID=1001 and Source=CRM, Native ID=2002) as follows:

{ 
  "content": { 
    "linkId": "58c17cd8aa3ebd23c7db43b8", 
    "identityGroupedBySource": [
      { "source": [ 
          { 
            "name":  "CRM",
            "id": "1001"
          } 
        ],
        "names": [ 
          { "name": { 
              "last": "SMITH", 
              "first": "JOHN"
          }, 
          "lastAsserted": "2017-02-12T12:34:23",
          "firstAsserted": "2017-02-12T12:34:23"
          } 
        ], 
        "ssns": [ 
          { "ssn": "999112222", 
            "lastAsserted": "2017-02-12T12:34:23", 
            "firstAsserted": "2017-02-12T12:34:23" 
          } 
        ], 
        "datesOfBirth": [ 
          { 
            "dateOfBirth": "19801204"),
          "lastAsserted": "2017-02-12T12:34:23", 
            "firstAsserted": "2017-02-12T12:34:23" 
          } 
        ] 
      },
      { 
        "source": [ 
          { "name": "CRM", 
            "id": "2002" 
          } 
       ], 
       "names": [ 
         { "name": {
             "last": "SMITH", 
             "first": "JOHNNY" 
         }, 
         "lastAsserted": "2017-02-19T09:11:48",
       "firstAsserted": "2017-02-19T09:11:48" 
         } 
      ], 
      "ssns": [ 
        { "ssn": "999112222", 
          "lastAsserted": "2017-02-19T09:11:48", 
          "firstAsserted": "2017-02-19T09:11:48" 
        } 
      ], 
      "datesOfBirth": [ 
         { "dateOfBirth": "19801204", 
           "lastAsserted": "2017-02-19T09:11:48", 
           "firstAsserted": "2017-02-19T09:11:48" 
         } 
       ]
     } 
   ] 
  }
} 

mergeIdentities example 2

Next suppose that the mergeIdentities service was called to merge Source=CRM, Native ID=2002 away into a retired state. The next time the Universal MPI entity is retrieved, the entity would look like this:

The following example is presented in the ‘GROUP BY SOURCE’ format, but the ‘DEFAULT’ format also behaves the same way, with a mergedSourceRecords array in the Identity object of the JSON response.
{
  "content": {
    "linkId": "58c17cd8aa3ebd23c7db43b8", 
    "identityGroupedBySource": [
      {
        "source": [
          {
            "name": "CRM",
            "id": "1001"
          }
      ],
        "names": [
          {
            "name": {
              "last": "SMITH",
              "first": "JOHN"
            },
            "lastAsserted": "2017-02-12T12:34:23",
            "firstAsserted": "2017-02-12T12:34:23"
            }
        ],
        "ssns": [
          {
            "ssn": "999112222",
            "lastAsserted": "2017-02-12T12:34:23",
            "firstAsserted": "2017-02-12T12:34:23"
          }
        ],
        "datesOfBirth": [
          {
            "dateOfBirth": "19801204",
            "lastAsserted": "2017-02-12T12:34:23",
            "firstAsserted": "2017-02-12T12:34:23"
          }
        ]
     },
     {
       "mergedSourceRecord": { 
         "name": "CRM",
         "id": "2002"
         }
       }
     ]
  }
}

The fact that the Universal MPI entity contains a retired/merged source record is conveyed, but the attribute values associated with the merged source record are hidden since the merged source record is retired and inactive.