linkIdentities

  • Web Services
  • UMPI
  • API Documentation
  • Universal Identity

The linkIdentities 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.

Note
With each linkIdentities request, we now automatically assess whether all records associated with the identity still belong together. Any records that do not align with this identity will be automatically unlinked, provided that this feature is enabled. For further details, please reach out to your Verato representative.

This service would be used on an exception basis, if you discover scenarios where you have external evidence that dictates that two of your source records are indeed the same person even though the demographic attribute data was not similar enough to cause them to match automatically in Universal Identity.

At the end of the operation, the two customer source records are linked together in a single Link ID within your Universal Identity instance. Any other source records to which they were previously linked (via matching) are also brought together in the single Link ID.

To minimize the turnover or ‘churn’ of assigned Link ID numbers, one of the existing Link IDs already assigned to one of the source records is retained, and the other existing Link ID is retired.

Sample URL

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

linkIdentities 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 whose Link ID should be retained – this is the “Link To” Source+Native ID
    • The Source+Native ID of the second customer record that should be forced to link into the “Link To” Source+Native ID – 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 “Link To” Link ID
  • The JSON object for the body of the request is as follows:

    {
      "trackingId": "string", 
      "content": {
        "linkToSource": { 
          "name": "string",
          "id": "string"
        },
        "source": { 
          "name": "string",
          "id": "string"
        }
      }
    }
    

linkIdentities 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 list of Source+Native ID values that are associated with the surviving Link ID (which would include both the Source+Native ID values from the request along with any other Source+Native ID values that were already linked via demographic matches)
  • 
    {
      "trackingId": "string", 
      "auditId": UUID, 
      "success": boolean, 
      "retryableError": boolean, 
      "message": "string", 
      "errors": [
        "string"
      ],
      "content": { 
          "linkId": "string",
          "linkToSource": {
            "name": "string",
            "id": "string"
           }
      }
    }