postIdentity

  • Web Services
  • UMPI
  • API Documentation

The postIdentity web service adds or updates your customer records into Universal MPI.

The Source + Native ID present on the Post Identity interaction dictates whether you are updating a customer record that was previously posted to Universal MPI or inserting a completely new customer record. Each time the Post Identity interaction is used, a LinkID is returned indicating the LinkID that was assigned to the customer record.

This could be a new LinkID or an existing LinkID, depending on whether the posted customer record matched any previously-posted customer records. LinkIDs are generated by the UMPI. 

Using the date attribute to set firstAsserted/lastAsserted

When posting a record to UMPI, you can set the firstAsserted and/or the lastAsserted date for the demographics in that record by using the date attribute in the identity.sources object in the postIdentity JSON.

  • This is an optional request value that is useful for clients who wish to post records while retaining the true ‘last updated’ datetime value from their data source.
  • If left empty, the current system datetime is used.

Time zone is assumed to be UTC, and the datetime format must be one of the following:

  • “YYYY-MM-DDThh:mm:ss”
  • “YYYY-MM-DD hh:mm:ss”
  • “YYYY-MM-DD” (in the last case, the hh:mm:ss is defaulted to 00:00:00)

See postIdentity request on this page for sample JSON.

Tip
This feature sets the firstAsserted and lastAsserted dates for all the demographic attribute data in the record up to the date provided in the postIdentity. If different dates are needed, multiple calls can be sent with subsets of demographics.

When using this feature for the initial post of a record (i.e., the record has not been sent to UMPI in the past), both the firstAsserted and the lastAsserted dates are set to the value in the postIdentity.

For example, if the postIdentity had "date": "2019-01-21", the result would be:

"firstAsserted": "2019-01-21T00:00:00",
"lastAsserted": "2019-01-21T00:00:00",

The lastAsserted date will self-correct the next time that record is posted without a date and will receive the datetime of the update post.

 How firstAsserted and lastAsserted are determined

In the case that the postIdentity is updating a record already in UMPI, logic is applied to determine to update firstAsserted or lastAsserted.

  • If the date in the postIdentity is prior to the firstAsserted date currently in UMPI, the date in postIdentity will replace the existing firstAsserted date in UMPI.
  • If the date in date in the postIdentity is later than the lastAsserted date currently in UMPI, the date in postIdentity will replace the existing lastAsserted date in UMPI

How to set firstAsserted and lastAsserted via API

In the case that both dates need to be set via API, two posts are required.​

  • The first post should set the firstAsserted date with a historical date value. It will also set both firstAsserted and lastAsserted to that historical date value.
  • The second post should set the lastAsserted date with a date after the firstAsserted and will set lastAsserted to the value in the post.​ Alternatively, the update post could not send in a date and the lastAsserted will receive the datetime of the update post.
Note
Any future updates that do not include a date, the lastAsserted date will be updated with datetime of the update post.

postIdentity request

  • The request includes:

    • A tracking ID (an optional identifier that the client can supply to track the response)
    • An identity object consisting of the following:
      • The Source+Native ID of the customer record being posted to Universal MPI (Note: each postIdentity transaction can only have one Source+Native ID)
      • The datetime value when the demographic attribute data was last updated in your source application. If left empty, the current system datetime is used. This is an  optional  request value that is useful for clients who wish to post records while retaining the true ‘last updated’ datetime value from their data source. The datetime format must be either “YYYY- MM-DDThh:mm:ss”, “YYYY-MM-DD hh:mm:ss”, or “YYYY-MM-DD” (in the last case, the hh:mm:ss is defaulted to 00:00:00).
      • The demographic attribute data
    • An optional string indicating which format to use in grouping Identity information in the web service response. The format options are ‘DEFAULT’ or ‘GROUP_BY_SOURCE’. If left blank, the ‘DEFAULT’ format is assumed. The ‘DEFAULT’ format groups the Identity information into a single Identity object; the ‘GROUP_BY_SOURCE’ format groups the Identity information into one object for each source record (Source + Native ID)
  • { 
        "trackingId": "string",
        "content": { 
          "responseIdentityFormatNames": ["string"], 
          "identity": {       
            "sources": [
              {
                "name": "string",
                "id": "string",
                "date": "string"
              }
           ],
           "emails": [
             "string"
                  ],
           "addresses": [ 
             {
               "line1": "string",
               "line2": "string",
               "city":  "string",
               "state": "string", 
               "postalCode": "string"
             }
           ],
           "names": [
             {
               "first":  "string",
               "middle": "string",
               "last":   "string", 
               "suffix": "string"
             }
           ],
           "ssns": [
             "string"
                  ],
           "genders": [
             "string"
             
           ],
           "datesOfBirth": [
             "string"
             
           ],
           "phoneNumbers": [
             {
               "number": "string",
               "areaCode": "string", 
               "extension": "string",
               "countryCode": "string"
             }
           ]
         }
       }
    }
    

postIdentity response

If you choose both the ‘DEFAULT’ and ‘GROUP_BY_SOURCE’ identity response formats, the response content will include the combination of both JSON examples described below.

  • 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 assigned to this identity
    • An identity object that echoes back the incoming identity data from the web service request
    • An identity object that details the full contents of the Universal MPI entity to which the incoming source record was assigned. The format of this identity object will vary depending on which format was requested in the web service request JSON.
    • An events object that describes any changes to LinkID assignment that occurred as a result of the postIdentity operation.

    For the request, each attribute and attribute cluster for the demographic data may have zero-to-many instances of data. So, for example, the request identity can include multiple addresses (or any other attribute) or no address.

    The "events":[] array within the JSON response is used to convey information about any events that resulted in a change in LinkID assignment for one or more Source + Native ID source records. The only events reported would be LinkID assignment changes that occurred as a result of the postIdentity operation – other actions that would result in a changed LinkID assignment, such as calling the delete, link, or unlink services, would not be included in the postIdentity response because they did not originate with the postIdentity operation.

  • {
      "trackingId": "string",
      "auditId": UUID,  
      "success": boolean,
      "retryableError": boolean,  
      "message": "string",   
        "errors": [
          "string"
      ],
       "content": {
           "linkId": "string",
           "linkIdentity": {
             "emails": [
                 "string"
            ],   
               "addresses": [
                {
                  "line1": "string",
                  "line2": "string",
                  "city": "string",
                  "state": "string",
                  "postalCode": "string"
                }
            ],
            "names": [
              {
                "first": "string",
                "middle": "string",
                "last": "string",
                "suffix": "string"
              }
            ],
            "ssns": [
               "string"
            ],
            "sources": [
              {
                "name": "string",
                "id": "string"
              }
            ],
            "linkId": "string",
            "genders": [
              "string"
            ],
            "datesOfBirth": [
              "string"
            ],
            "phoneNumbers": [
              {
                "number": "string",
                "areaCode": "string",
                "extension": "string",
                "countryCode": "string"
              }
            ]
          },
          "incomingIdentity": {
          "emails": [
            "string"
          ],
          "addresses": [
            {
              "line1": "string",
              "line2": "string",
              "city": "string",
              "state": "string",
              "postalCode": "string"
            }
          ],
          "names": [
            {
             "first": "string",
             "middle": "string",
             "last": "string",
             "suffix": "string"
            }
          ],
          "ssns": [
            "string"
          ],
          "sources": [
            {
              "name": "string",
              "id": "string"
            }
          ],
          "linkId": "string",
          "genders": [
            "string"
          ],
          "datesOfBirth": [
            "string"
          ],
          "phoneNumbers": [
            {
              "number": "string",
              "areaCode": "string",
              "extension": "string",
              "countryCode": "string"
            }
           ]
         },
         "events": []
      }
    }
  • The GROUP BY SOURCE response identity format allows the web service caller to get a different, more granular format or view of the original source data in the event that more granular format is needed.

    The GROUP_BY_SOURCE response identity format groups the identity information by each distinct Source + Native ID source record that contributed to the overall Universal MPI entity. In addition, each attribute cluster also includes the datetime on which the attribute value was last asserted (the last datetime this attribute value was included in a postIdentity web service request for the Source + Native ID source record) and the datetime on which the attribute value was first asserted.

    {
       "trackingId", "string",
       "auditId", UUID,
       "success", UUID,
       "retryableError", UUID,
       "message", "string",
       "errors", [
         "string"
         ],
       "content", {
         "linkId", "string",
         "identityGroupedBySource", [
           {
             "emails", [
             {
               "email", "string",
               "lastAsserted", "string",
               "firstAsserted", "string"
             }
             ],
             "addresses", [
               {
               "address", {
                 "city", "string",
                 "postalCode", "string",
                 "state", "string",
                 "line2", "string",
                 "line1", "string"
               },
               "lastAsserted", "string",
               "firstAsserted", "string"
             }
           ],
           "names", [
             {
               "name", {
               "middle", "string",
               "last", "string",
               "suffix", "string",
               "first", "string"
             },
             "lastAsserted", "string",
             "firstAsserted", "string"
             }
         ],
           "ssns", [
             {
             "ssn", "string",
             "lastAsserted", "string",
             "firstAsserted", "string"
             }
         ],
           "genders", [
             {
             "gender", "string",
             "lastAsserted", "string",
             "firstAsserted", "string"
             }
           ],
           "source", {
             "name", "string",
             "id", "string"
               },
           "datesOfBirth", [
             {
             "dateOfBirth", "string",
             "lastAsserted", "string",
             "firstAsserted", "string"
             }
         ],
           "phoneNumbers", [
             {
             "phoneNumber", {
             "number", "string",
             "areaCode", "string",
             "extension", "string",
             "countryCode", "string"
             },
             "lastAsserted", "string",
             "firstAsserted", "string"
           }
         ]
       }
     ],
         "incomingIdentity", {
           "emails", [
           "string"
             ],
           "addresses", [
             {
               "line1", "string",
               "line2", "string",
               "city", "string",
               "state", "string",
               "postalCode", "string"
            }
         ],
         "names", [
           {
             "first", "string",
             "middle", "string",
             "last", "string",
             "suffix", "string"
           }
         ],
         "ssns", [
           "string"
         ],
         "sources", [
           {
             "name", "string",
             "id", "string"
           }
         ],
         "linkId", "string",
         "genders", [
           "string"
         ],
         "datesOfBirth", [
           "string"
         ],
         "phoneNumbers", [
           {
             "number", "string",
             "areaCode", "string",
             "extension", "string",
             "countryCode", "string"
           }
         ]
       },
       "events", []
       }
    ]

postIdentity JSON response events

There are two types of events that can be included in the JSON response, each with a slightly different JSON structure.

Event information is included in the JSON response only in cases where there has been a change in LinkID assignment. If no new Source + Native ID source record was added, and no existing source records received a LinkID assignment change, then the “events” array in the JSON response will be empty.

Event Type

Event Array

ADD_SOURCE

The ADD_SOURCE event type is included in the JSON response when a Source + Native ID is added to Universal MPI for the first time.

With this event, the Source + Native ID did not have any assigned LinkID before postIdentity was called, so the postIdentity operation represents a change to the LinkID assignment for the submitted Source + Native ID.

There can only be a single ADD_SOURCE event type within a postIdentity response, since you can only add one Source + Native ID at a time in the postIdentity web service.

{
 "type": "ADD_SOURCE",
  "source": 
  { 
    "name": "string",
    "id": "string"
  }
}

UPDATE_SOURCE

The UPDATE_SOURCE event type is included in the JSON response when one or more Source + Native ID source records receives a change to its previously-assigned LinkID.

  • It’s possible that the Source + Native ID submitted in the postIdentity request is the Source + Native ID that receives a LinkID change.
  • It's also possible that a different Source + Native ID other than the one submitted in the postIdentity response is the Source + Native ID that receives a LinkID change. This would happen if two or more pre-existing LinkIDs were linked together due to transitive linking in the matching process. 

There can be multiple UPDATE_SOURCE events within a postIdentity response if there are multiple pre-existing LinkIDs that get linked together in a transitive linking match scenario. In this case, each UPDATE_SOURCE object in the array corresponds to one previous LinkID, which could have contained one or multiple Source + Native ID values.

{
  "type": "UPDATE_SOURCE",
  "previousLinkId": "string", 
  "sources": [
    { 
      "name": "string",
      "id": "string"
    }
  ]
} 

postIdentity example 1

  • As an example, suppose that last week you posted to Universal MPI a customer record from your CRM data source, with the local/native ID of 1001 within the CRM data source. At the time, there was no matching identity in Universal MPI, so a new LinkID was assigned.

  • {
      "trackingId": "post-record-20170212-0001", 
      "content": {
        "identity": {
          "sources": [
            {
              "name": "CRM",
              "id": "1001"
            }
         ],
          "emails": [ ""
         ],
          "addresses": [
            {
              "line1": "",
              "line2": "",
              "city": "",
              "state": "",
              "postalCode": ""
            }
          ],
          "names": [
            {
              "first": "JOHN",
              "last": "SMITH"
            }
          ],
           "ssns": [ "999112222"
          ],
          "genders": [ ""
          ],
          "datesOfBirth": [ 
            "19801204"
          ],
          "phoneNumbers": [
            {
              "number": "",
              "areaCode": "",
              "extension": "",
              "countryCode": ""
            }
           ]
          }
         }
       }
  • {
      "trackingId": "post-record-20170212-0001",   
      "auditId": "6dd464bf-4612-4fd7-bc3e-9b931aaff12d",
      "success": true,
      "retryableError": false,
      "message": "The identity has been successfully posted.",   
      "content": {
        "linkId": "58c17cd8aa3ebd23c7db43b8",     
        "linkIdentity": {
          "names": [
            {
              "first": "JOHN",
              "last": "SMITH"
            }
          ],
          "ssns": [ "999112222"
          ],
          "sources": [
            {
              "name": "CRM",
              "id": "1001"
            }
          ],
          "linkId": "58c17cd8aa3ebd23c7db43b8",       
          "datesOfBirth": [
            "19801204"
          ]
       },
       "incomingIdentity": {      
       "names": [
           {
             "first": "JOHN",
             "last": "SMITH"
           }      ],
         "ssns": [ "999112222"
           ],
           "sources": [
             {
               "name": "CRM",
               "id": "1001"
             }
           ],
           "datesOfBirth": [ "19801204"
           ]
         },
           "events": [
             {"type": "ADD_SOURCE",
                "source": {             
                "name": "CRM",
                "id": "1001"
             }
           }
         ]
       }
    }
    

Example 1 results

  • At the end of the postIdentity operation, a new Universal MPI entity with LinkID=58c17cd8aa3ebc23c7db43b8 is created.
  • The Universal MPI entity contains only the Source + Native ID and attribute data from the CRM:1001 record.
  • Because this was the first time that CRM:1001 was added to Universal MPI, the ADD_SOURCE event type was reported in the web service response JSON.

postIdentity example 2

  • Now suppose that a week later you post another customer record from your CRM data source, with the local/native ID of 2002 within the CRM data source. This is a different record in the CRM data source than 1001 (the previously-posted record), but the demographic attribute data is close enough that it matches to the previously-posted customer record.

    So, the same LinkID should be returned, and the resulting Universal MPI entity should be made up of both the CRM:1001 and CRM:2002 customer records.

  • {
      "trackingId": "post-record-20170219-0074", 
        "content": {
        "identity": {
          "sources": [
            {
              "name": "CRM",
              "id": "2002"
            }
         ],
         "emails": [ ""
         ],
         "addresses": [
            {
              "line1": "",
              "line2": "",
              "city": "",
              "state": "",
              "postalCode": ""
            }
         ],
         "names": [
            {
              "first": "JOHNNY",
              "last": "SMITH"
            }
         ],
         "ssns": [ 
                "999112222"
         ],
         "genders": [ 
                ""
         ],
           "datesOfBirth": [ 
              "19801204"
         ],
           "phoneNumbers": [
             {
               "number": "",
               "areaCode": "",
               "extension": "",
               "countryCode": ""
             }
          ]
        }
      }
    }
    
  • The response confirms that the same LinkID was assigned, and the LinkID represents a single Universal MPI entity which is made up of both CRM:1001 and CRM:2002. Because this was the first time that CRM:2002 was added to Universal MPI, the ADD_SOURCE event type was reported in the web service response JSON. Because CRM:1001, which also is assigned to the same LinkID, did  NOT  undergo any change in its LinkID assignment, there was no additional event type reported in the web service response JSON.

    {
       "trackingId": "post-record-20170219-0074", 
       "auditId": "6dd464bf-4612-4fd7-bc3e-9b931aaff12d", 
       "success": true,
       "retryableError": false,
       "message": "The identity has been successfully posted.", 
       "content": {
         "linkId": "58c17cd8aa3ebd23c7db43b8", 
         "linkIdentity": {
           "names": [
             {
               "first": "JOHN",
               "last": "SMITH"
             },
             {
               "first": "JOHNNY",
               "last": "SMITH"
             }
           ],
           "ssns": [ 
             "999112222"
           ],
           "sources": [
             {
               "name": "CRM",
               "id": "1001"
             },
             {
               "name": "CRM",
               "id": "2002"
             }
           ],
           "linkId": "58c17cd8aa3ebd23c7db43b8", 
           "datesOfBirth": [
             "19801204"
           ],
         },
            "incomingIdentity": { 
            "names": [
              {
                "first": "JOHNNY",
                "last": "SMITH" 
              }
           ],
           "ssns": [ "999112222"
           ],
           "sources": [
             {
               "name": "CRM",
               "id": "2002"
             }
           ],
           "datesOfBirth": [ 
             "19801204"
           ]
        },
          "events": [
            {"type": "ADD_SOURCE",
              "source": {
              "name": "CRM",
              "id": "2002"
            }
          }
        ]
      }
    }
    
  • If the second postIdentity call had instead specified the ‘GROUP_BY_SOURCE’ option, the web service response would have instead looked like this:

    {
      "trackingId": "post-record-20170219-0074", 
      "auditId": "6dd464bf-4612-4fd7-bc3e-9b931aaff12d",
      "success": true,
      "retryableError": false,
      "message": "The identity has been successfully posted.", 
      "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"
             }
            ]
          }
        ],
        "incomingIdentity": { 
          "names": [
            {
              "first": "JOHNNY",
              "last": "SMITH"
            }
          ],
          "ssns": [ 
            "999112222"
          ],
          "sources": [
            {
              "name": "CRM",
              "id": "2002"
            }
          ],
          "datesOfBirth": [
            "19801204"
            ]
        },
        "events": [
          {"type": "ADD_SOURCE",
            "source": { 
            "name": "CRM",
            "id": "2002"
           }
          }
        ]
      }
    } 

In previous example, LinkID 58c17cd8aa3ebd23c7db43b8 contains source records CRM:1001 and CRM:2002. Now, imagine that a second LinkID, 145abdb8772c79826ac69191, also exists containing source records CRM:3003 and CRM:4004.

Example 3 JSON response

Next, suppose that another postIdentity update was submitted for CRM:1001, and the new demographic data caused the matching algorithm to realize that all four source records are now a match – in the postIdentity operation, LinkID 145abdb8772c79826ac69191 would be matched and linked into LinkID 58c17cd8aa3ebd23c7db43b8.

In this case, the postIdentity web service response would indicate that all four source records are now included in the resulting LinkID 58c17cd8aa3ebd23c7db43b8, and the postIdentity response would also include the following information in the events array:

{
  "type": "UPDATE_SOURCE",
  "previousLinkId": "145abdb8772c79826ac69191", 
  "sources": [
    {
      "name": "CRM",
      "id": "3003"
    },
    {
      "name": "CRM",
      "id": "4004"
    }
  ]
}