The postIdentity web service adds or updates your customer records into Universal Identity.
The Source + Native ID present on the Post Identity interaction dictates whether you are updating a customer record that was previously posted to Universal Identity or inserting a completely new customer record. Each time the Post Identity interaction is used, a Link ID is returned indicating the Link ID that was assigned to the customer record.
This could be a new Link ID or an existing Link ID, depending on whether the posted customer record matched any previously-posted customer records. Link IDs are generated by the Universal Identity platform.
For more information about using postIdentity to add and update, see the following video:
Using the date attribute to set firstAsserted/lastAsserted
When posting a record to Universal Identity, 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)
We expect the timestamp to be in 24-hour format and do not support 12-hour format.
See postIdentity request on this page for sample JSON.
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 Universal Identity 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 Universal Identity, logic is applied to determine to update firstAsserted or lastAsserted.
- If the date in the postIdentity is prior to the firstAsserted date currently in the Universal Identity platform, the date in postIdentity will replace the existing firstAsserted date in Universal Identity.
- If the date in date in the postIdentity is later than the lastAsserted date currently in the Universal Identity platform, the date in postIdentity will replace the existing lastAsserted date in Universal Identity.
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.
Any future updates that do not include a date, the lastAsserted date will be updated with datetime of the update post.
Sample URL
The URL for this request is of the format https://custXXXX.verato-connect.com/link-ws/svc/postIdentity, where XXXX is a 4-digit number.
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 Identity (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).
- metadata: Optional information that can be included along with the request. It consists of the following fields:
- sourceLoginName: A string representing the username of the user who made a change in the source system.
- sourceUserName: A string representing the full name of the user who made a change in the source system.
- location: A string indicating the location where the change was made in the source system.
- transactionType: A string indicating the type of transaction in the source system (e.g. Patient Admit or Patient Discharge).
- 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’, ‘GROUP_BY_SOURCE’, or specific smart view (or views).
-
- If left blank, the ‘DEFAULT’ format is assumed. The ‘DEFAULT’ format groups the identity information into a single Identity object
- ‘GROUP_BY_SOURCE’ format groups the identity information into one object for each source record (Source + Native ID)
- Smart View(s) return identity information as configured
-
-
{ "trackingId": "string", "content": { "responseIdentityFormatNames": ["string"], "identity": { "sources": [{ "name": "string", "id": "string", "date": "string", "metadata": { "sourceLoginName": "string", "sourceUserName": "string", "location": "string", "transactionType": "string" } }], "emails": [ "string1", { "email": "string2", "type": "string" } ], "addresses": [{ "line1": "string", "line2": "string", "city": "string", "state": "string", "postalCode": "string", "country": "string", "type": "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", "type": "string" }], "deathDetails": [{ "deceased": "char", "dateOfDeath": "string", "city": "string", "county": "string", "state": "string", "country": "string" }], "externalUniqueIdentifier": [{ "issuer": "string", "value": "string", "status": "string", "startDate": "string", "endDate": "string" }], "alternateIdentifiers": [{ "type": "string", "issuer": "string", "value": "string", "startDate": "string", "endDate": "string" }], "healthInsuranceCoverage": [{ "payerName": "string", "planType": "string", "groupNumber": "string", "idNumber": "string", "subscriberId": "string", "sequenceNumber": "string", "effectiveDate": "string", "endDate": "string" }], "guarantor": [{ "relationship": "string", "firstName": "string", "lastName": "string", "ssn": "string" }], "multipleBirthIndicator": [{ "multipleBirthIndicator": "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 Link ID 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 Identity 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.
Note
Verato Universal Identity now offers real-time, CASS-certified U.S. address verification. When enabled, this feature enriches all addresses within the identity with extra details. These include residential status, vacancy status, extended ZIP code, geographical coordinates, and more. Every address in the API response will also contain additional fields, as detailed here. - Metadata information, if specified in the request. It consists of the following fields:
- sourceLoginName: An echo of the username specified in the request.
- sourceUserName: An echo of the full name of the user specified in the request.
- location: An echo of the location specified in the request.
- transactionType: An echo of the type of transaction specified in the request.
- transactionDateTime: The datetime when the postIdentity request was processed.
- sourceTransactionDateTime: This field echoes the datetime value if it is specified in the request. Otherwise, it is set as the datetime when the request was processed.
Currently, the response also includes an empty customMetaData field. This field is meant to store any custom metadata that you want to include in the postIdentity request, separate from the fields mentioned above. Note that including customMetadata is currently not supported.- An events object that describes any changes to Link ID 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 Link ID assignment for one or more Source + Native ID source records. The only events reported would be Link ID assignment changes that occurred as a result of the postIdentity operation – other actions that would result in a changed Link ID 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. - The metadata information returned in the "DEFAULT" response corresponds to the initially asserted metadata. To keep track of the first and last asserted values for the metadata, use the "GROUP_BY_SOURCE" response.
{ "trackingId": "string", "auditId": "UUID", "message": "string", "success": boolean, "retryableError": boolean, "errors": [ "string" ], "content": { "linkIdentity": { "linkId": "UUID", "sources": [ { "name": "string", "id": "string", "date": "string", "metadata": { "transactionDateTime": "string", "sourceTransactionDateTime": "string", "sourceLoginName": "string", "sourceUserName": "string", "location": "string", "transactionType": "string", "customMetaData": {} } } ], "mergedSourceRecords": [], "names": [ { "first": "string", "middle": "string", "last": "string", "suffix": "string" } ], "datesOfBirth": [ "string" ], "ssns": [ "string" ], "addresses": [ { "line1": " string", "line2": "string", "city": "string", "state": "string", "postalCode": "string", "country": "string", "type": "string" } ], "genders": [ "string" ], "emails": [ "string1", "string2" ], "phoneNumbers": [ { "countryCode": "string", "areaCode": "string", "number": "string", "extension": "string", "type": "string" } ], "unmergeable": [], "deathDetails": [ { "deceased": "char", "dateOfDeath": "string", "city": "string", "county": "string", "state": "string", "country": "string" } ], "alternateIdentifiers": [ { "endDate": "string", "type": "string", "value": "string", "issuer": "string", "startDate": "string" } ], "multipleBirthIndicator": [ { "multipleBirthIndicator": "string" } ], "healthInsuranceCoverage": [ { "sequenceNumber": "string", "planType": "string", "endDate": "string", "payerName": "string", "subscriberId": "string", "idNumber": "string", "groupNumber": "string", "effectiveDate": "string" } ], "externalUniqueIdentifier": [ { "endDate": "string", "value": "string", "issuer": "string", "startDate": "string", "status": "string" } ], "guarantor": [ { "firstName": "string", "lastName": "string", "relationship": "string", "ssn": "string" } ] }, "linkId": "UUID", "incomingIdentity": { "sources": [ { "name": "string", "id": "string", "metadata": { "sourceLoginName": "string", "sourceUserName": "string", "location": "string", "transactionType": "string" } } ], "mergedSourceRecords": [], "names": [ { "first": "string", "middle": "string", "last": "string", "suffix": "string" } ], "datesOfBirth": [ "string" ], "ssns": [ "string" ], "addresses": [ { "line1": "string", "line2": "string", "city": "string", "state": "string", "postalCode": "string", "country": "string", "type": "string" } ], "genders": [ "string" ], "emails": [ "string1", "string2", ], "phoneNumbers": [ { "countryCode": "string", "areaCode": "string", "number": "string", "extension": "string", "type": "string" } ], "unmergeable": [], "deathDetails": [ { "deceased": "char", "dateOfDeath": "string", "city": "string", "county": "string", "state": "string", "country": "string" } ], "alternateIdentifiers": [ { "type": "string", "issuer": "string", "value": "string", "startDate": "string", "endDate": "string" } ], "multipleBirthIndicator": [ { "multipleBirthIndicator": "string" } ], "healthInsuranceCoverage": [ { "payerName": "string", "planType": "string", "groupNumber": "string", "idNumber": "string", "subscriberId": "string", "sequenceNumber": "string", "effectiveDate": "string", "endDate": "string" } ], "externalUniqueIdentifier": [ { "issuer": "string", "value": "string", "status": "string", "startDate": "string", "endDate": "string" } ], "guarantor": [ { "relationship": "string", "firstName": "string", "lastName": "string", "ssn": "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 Identity 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", "message": "string", "success": boolean, "retryableError": boolean, "errors": [ "string" ], "content": { "linkId": "UUID", "identityGroupedBySource": [ { "source": { "name": "string", "id": "string", "metadata": { "transactionDateTime": "string", "sourceTransactionDateTime": "string", "sourceLoginName": "string", "sourceUserName": "string", "location": "string", "transactionType": "string", "customMetaData": {} } }, "names": [ { "firstAsserted": "string", "lastAsserted": "string", "firstAssertedMetadata": { "transactionDateTime": "string", "sourceTransactionDateTime": "string", "sourceLoginName": "string", "sourceUserName": "string", "location": "string", "transactionType": "string", "customMetaData": {} }, "lastAssertedMetadata": { "transactionDateTime": "string", "sourceTransactionDateTime": "string", "sourceLoginName": "string", "sourceUserName": "string", "location": "string", "transactionType": "string", "customMetaData": {} }, "name": { "first": "string", "middle": "string", "last": "string", "suffix": "string" } } ], "datesOfBirth": [ { "firstAsserted": "string", "lastAsserted": "string", "firstAssertedMetadata": { "transactionDateTime": "string", "sourceTransactionDateTime": "string", "sourceLoginName": "string", "sourceUserName": "string", "location": "string", "transactionType": "string", "customMetaData": {} }, "lastAssertedMetadata": { "transactionDateTime": "string", "sourceTransactionDateTime": "string", "sourceLoginName": "string", "sourceUserName": "string", "location": "string", "transactionType": "string", "customMetaData": {} }, "dateOfBirth": "string" } ], "ssns": [ { "firstAsserted": "string", "lastAsserted": "string", "firstAssertedMetadata": { "transactionDateTime": "string", "sourceTransactionDateTime": "string", "sourceLoginName": "string", "sourceUserName": "string", "location": "string", "transactionType": "string", "customMetaData": {} }, "lastAssertedMetadata": { "transactionDateTime": "string", "sourceTransactionDateTime": "string", "sourceLoginName": "string", "sourceUserName": "string", "location": "string", "transactionType": "string", "customMetaData": {} }, "ssn": "string" } ], "addresses": [ { "firstAsserted": "string", "lastAsserted": "string", "firstAssertedMetadata": { "transactionDateTime": "string", "sourceTransactionDateTime": "string", "sourceLoginName": "string", "sourceUserName": "string", "location": "string", "transactionType": "string", "customMetaData": {} }, "lastAssertedMetadata": { "transactionDateTime": "string", "sourceTransactionDateTime": "string", "sourceLoginName": "string", "sourceUserName": "string", "location": "string", "transactionType": "string", "customMetaData": {} }, "address": { "line1": " string", "line2": "string", "city": "string", "state": "string", "postalCode": "string", "country": "string", "type": "string" } } ], "addressDetails": [], "genders": [ { "firstAsserted": "string", "lastAsserted": "string", "firstAssertedMetadata": { "transactionDateTime": "string", "sourceTransactionDateTime": "string", "sourceLoginName": "string", "sourceUserName": "string", "location": "string", "transactionType": "string", "customMetaData": {} }, "lastAssertedMetadata": { "transactionDateTime": "string", "sourceTransactionDateTime": "string", "sourceLoginName": "string", "sourceUserName": "string", "location": "string", "transactionType": "string", "customMetaData": {} }, "gender": "string" } ], "emails": [ { "firstAsserted": "string", "lastAsserted": "string", "firstAssertedMetadata": { "transactionDateTime": "string", "sourceTransactionDateTime": "string", "sourceLoginName": "string", "sourceUserName": "string", "location": "string", "transactionType": "string", "customMetaData": {} }, "lastAssertedMetadata": { "transactionDateTime": "string", "sourceTransactionDateTime": "string", "sourceLoginName": "string", "sourceUserName": "string", "location": "string", "transactionType": "string", "customMetaData": {} }, "email": "string1" }, { "firstAsserted": "string", "lastAsserted": "string", "firstAssertedMetadata": { "transactionDateTime": "string", "sourceTransactionDateTime": "string", "sourceLoginName": "string", "sourceUserName": "string", "location": "string", "transactionType": "string", "customMetaData": {} }, "lastAssertedMetadata": { "transactionDateTime": "string", "sourceTransactionDateTime": "string", "sourceLoginName": "string", "sourceUserName": "string", "location": "string", "transactionType": "string", "customMetaData": {} }, "email": "string2" } ], "phoneNumbers": [ { "firstAsserted": "string", "lastAsserted": "string", "firstAssertedMetadata": { "transactionDateTime": "string", "sourceTransactionDateTime": "string", "sourceLoginName": "string", "sourceUserName": "string", "location": "string", "transactionType": "string", "customMetaData": {} }, "lastAssertedMetadata": { "transactionDateTime": "string", "sourceTransactionDateTime": "string", "sourceLoginName": "string", "sourceUserName": "string", "location": "string", "transactionType": "string", "customMetaData": {} }, "phoneNumber": { "countryCode": "string", "areaCode": "string", "number": "string", "extension": "string", "type": "string" } } ], "deathDetails": [ { "firstAsserted": "string", "lastAsserted": "string", "firstAssertedMetadata": { "transactionDateTime": "string", "sourceTransactionDateTime": "string", "sourceLoginName": "string", "sourceUserName": "string", "location": "string", "transactionType": "string", "customMetaData": {} }, "lastAssertedMetadata": { "transactionDateTime": "string", "sourceTransactionDateTime": "string", "sourceLoginName": "string", "sourceUserName": "string", "location": "string", "transactionType": "string", "customMetaData": {} }, "deathDetails": { "deceased": "char", "dateOfDeath": "string", "city": "string", "county": "string", "state": "string", "country": "string" } } ], "externalUniqueIdentifiers": [ { "firstAsserted": "string", "lastAsserted": "string", "firstAssertedMetadata": { "transactionDateTime": "string", "sourceTransactionDateTime": "string", "sourceLoginName": "string", "sourceUserName": "string", "location": "string", "transactionType": "string", "customMetaData": {} }, "lastAssertedMetadata": { "transactionDateTime": "string", "sourceTransactionDateTime": "string", "sourceLoginName": "string", "sourceUserName": "string", "location": "string", "transactionType": "string", "customMetaData": {} }, "externalUniqueIdentifier": { "endDate": "string", "value": "string", "startDate": "string", "issuer": "string", "status": "string" } } ], "alternateIdentifiers": [ { "firstAsserted": "string", "lastAsserted": "string", "firstAssertedMetadata": { "transactionDateTime": "string", "sourceTransactionDateTime": "string", "sourceLoginName": "string", "sourceUserName": "string", "location": "string", "transactionType": "string", "customMetaData": {} }, "lastAssertedMetadata": { "transactionDateTime": "string", "sourceTransactionDateTime": "string", "sourceLoginName": "string", "sourceUserName": "string", "location": "string", "transactionType": "string", "customMetaData": {} }, "alternateIdentifiers": { "endDate": "string", "type": "string", "value": "string", "startDate": "string", "issuer": "string" } } ], "multipleBirthIndicators": [ { "firstAsserted": "string", "lastAsserted": "string", "firstAssertedMetadata": { "transactionDateTime": "string", "sourceTransactionDateTime": "string", "sourceLoginName": "string", "sourceUserName": "string", "location": "string", "transactionType": "string", "customMetaData": {} }, "lastAssertedMetadata": { "transactionDateTime": "string", "sourceTransactionDateTime": "string", "sourceLoginName": "string", "sourceUserName": "string", "location": "string", "transactionType": "string", "customMetaData": {} }, "multipleBirthIndicator": { "multipleBirthIndicator": "string" } } ], "healthInsuranceCoverages": [ { "firstAsserted": "string", "lastAsserted": "string", "firstAssertedMetadata": { "transactionDateTime": "string", "sourceTransactionDateTime": "string", "sourceLoginName": "string", "sourceUserName": "string", "location": "string", "transactionType": "string", "customMetaData": {} }, "lastAssertedMetadata": { "transactionDateTime": "string", "sourceTransactionDateTime": "string", "sourceLoginName": "string", "sourceUserName": "string", "location": "string", "transactionType": "string", "customMetaData": {} }, "healthInsuranceCoverage": { "sequenceNumber": "string", "planType": "string", "endDate": "string", "payerName": "string", "subscriberId": "string", "idNumber": "string", "groupNumber": "string", "effectiveDate": "string" } } ], "guarantors": [ { "firstAsserted": "string", "lastAsserted": "string", "firstAssertedMetadata": { "transactionDateTime": "string", "sourceTransactionDateTime": "string", "sourceLoginName": "string", "sourceUserName": "string", "location": "string", "transactionType": "string", "customMetaData": {} }, "lastAssertedMetadata": { "transactionDateTime": "string", "sourceTransactionDateTime": "string", "sourceLoginName": "string", "sourceUserName": "string", "location": "string", "transactionType": "string", "customMetaData": {} }, "guarantor": { "lastName": "string", "firstName": "string", "relationship": "string", "ssn": "string" } } ] } ], "incomingIdentity": { "sources": [ { "name": "string", "id": "string", "metadata": { "sourceLoginName": "string", "sourceUserName": "string", "location": "string", "transactionType": "string" } } ], "mergedSourceRecords": [], "names": [ { "first": "string", "middle": "string", "last": "string", "suffix": "string" } ], "datesOfBirth": [ "string" ], "ssns": [ "string" ], "addresses": [ { "line1": "string", "line2": "string", "city": "string", "state": "string", "postalCode": "string", "country": "string", "type": "string" } ], "genders": [ "string" ], "emails": [ "string1", "string2" ], "phoneNumbers": [ { "countryCode": "string", "areaCode": "string", "number": "string", "extension": "string", "type": "string" } ], "unmergeable": [], "deathDetails": [ { "deceased": "char", "dateOfDeath": "string", "city": "string", "county": "string", "state": "string", "country": "string" } ], "alternateIdentifiers": [ { "type": "string", "issuer": "string", "value": "string", "startDate": "string", "endDate": "string" } ], "multipleBirthIndicator": [ { "multipleBirthIndicator": "string" } ], "healthInsuranceCoverage": [ { "payerName": "string", "planType": "string", "groupNumber": "string", "idNumber": "string", "subscriberId": "string", "sequenceNumber": "string", "effectiveDate": "string", "endDate": "string" } ], "externalUniqueIdentifier": [ { "issuer": "string", "value": "string", "status": "string", "startDate": "string", "endDate": "string" } ], "guarantor": [ { "relationship": "string", "firstName": "string", "lastName": "string", "ssn": "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 Link ID assignment. If no new Source + Native ID source record was added, and no existing source records received a Link ID 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 Identity for the first time. With this event, the Source + Native ID did not have any assigned Link ID before postIdentity was called, so the postIdentity operation represents a change to the Link ID 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. |
|
|
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 Link ID.
There can be multiple UPDATE_SOURCE events within a postIdentity response if there are multiple pre-existing Link IDs that get linked together in a transitive linking match scenario. In this case, each UPDATE_SOURCE object in the array corresponds to one previous Link ID, which could have contained one or multiple Source + Native ID values. |
|
postIdentity example 1
-
As an example, suppose that last week you posted to Universal Identity 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 Identity, so a new Link ID 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 Identity entity with Link ID=58c17cd8aa3ebc23c7db43b8 is created.
- The Universal Identity 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 Identity, 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 Link ID should be returned, and the resulting Universal Identity 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 Link ID was assigned, and the Link ID represents a single Universal Identity 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 Identity, the ADD_SOURCE event type was reported in the web service response JSON. Because CRM:1001, which also is assigned to the same Link ID, did NOT undergo any change in its Link ID 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, Link ID 58c17cd8aa3ebd23c7db43b8 contains source records CRM:1001 and CRM:2002. Now, imagine that a second Link ID, 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, Link ID 145abdb8772c79826ac69191 would be matched and linked into Link ID 58c17cd8aa3ebd23c7db43b8.
In this case, the postIdentity web service response would indicate that all four source records are now included in the resulting Link ID 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"
}
]
}