mergeIdentities

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 Link ID 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 Identity 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 Identity instance when a corresponding merge has already been applied to the source system.

Applying mergeIdentities to 2 source records in different Link IDs

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

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

If the overall surviving Universal Identity 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.

Sample URL

The URL for this request is of the format https://custXXXX.verato-connect.com/link-ws/svc/mergeIdentities, where XXXX is a 4-digit number.

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 Link ID for this second customer record is retired, and all the source records previously associated with this Link ID are moved into the surviving Link ID

• {
    "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 Link ID of the single surviving Universal Identity 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 (Link ID) 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 Link ID 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 Identity entity is retrieved, the entity would look like this:

{
  "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 Identity 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.