The postIdentity web service adds or updates your customer records into Provider Data Management.
Each of your provider records is uniquely identified by the source system/application from which it came, a unique local identifier within that source system/application, and an entity type code. The first two elements are known as the Source and the Native ID.
- The Source + Native ID present on the postIdentity interaction dictates whether you are updating a customer record that was previously posted to Provider Data Management 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 Provider Data Management.
The third component is the Entity Type Code, which indicates whether a record represents an individual practitioner (Entity Type Code 1) or an organization (Entity Type Code 2). Together, the Source, Native ID, and Entity Type Code uniquely identify each provider record.
This unique combination is crucial for ensuring accurate updates to provider data. When updates occur in your local source system or application, you communicate these changes to Provider Data Management using the Source, Native ID, and Entity Type Code. If Provider Data Management recognizes this combination as one it has seen before, it treats the submission as an update to an existing record. Otherwise, it interprets the information as a new record.
The Source is a unique code that identifies the origin of a record. It must not contain any whitespace characters and is configured in your instance of Provider Data Management. The configuration system also maps Source codes to the user accounts that are authorized to access them.
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 Provider Data Management, 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 Provider Data Management, logic is applied to determine to update firstAsserted or lastAsserted.
- If the date in the postIdentity is prior to the firstAsserted date currently in Provider Data Management, the date in postIdentity will replace the existing firstAsserted date in Provider Data Management.
- If the date in date in the postIdentity is later than the lastAsserted date currently in Provider Data Management, the date in postIdentity will replace the existing lastAsserted date in Provider Data Management.
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-provider.verato-connect.com/provider-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).
- 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": [ { "date": "string", "name": "string", "id": "string" } ], "addresses": [ { "line1": "string", "line2": "string", "city": "string", "state": "string", "postalCode": "string" } ], "locationInfo": [ { "coloCode": "string", "ruralUrbanSuburban": "string" } ], "education": [ { "gradYear": "string", "medSchool": "string" } ], "genders": [ "string" ], "phoneNumbers": [ { "number": "string", "type": "string" } ], "emails": [ "string" ], "license": [ { "number": "string", "state": "string", "taxonomyCode": "string", "licenseStatus": "string", "licenseStatusDetail": "string", "licenseEffectiveDate": "string", "licenseExpirationDate": "string", "licenseProfessionCode": "string", "licenseProfessionRankCode": "string", "licenseLastUpdateDate": "string" } ], "specialties": [ { "specialtyTaxonomyCode": "string" } ], "contactInformation": [ { "address": { "addressType": "string", "addressName": "string", "line1": "string", "line2": "string", "city": "string", "state": "string", "postalCode": "string" }, "phoneList": [ { "type": " string ", "number": "string" } ], "faxList": [ { "type": "string", "number": "string" } ] } ], "disciplinaryInfo": [ { "exclusionType": "string", "warning": "string" } ], "groupTaxonomies": [ { "groupTaxonomyCode": "string" } ], "organizationNames": [ { "otherOrgName": "string", "legalBusinessName": "string", "parentOrgName": "string" } ], "names": [ { "first": "string", "middle": "string", "last": "string", "credential": "string", "prefix": "string", "suffix": "string" } ], "faxNumbers": [ { "number": "string", "type": "string" } ], "medicareInfo": [ { "inPecos": "string", "acceptsMedicare": "string" } ], "practiceInfo": [ { "estimatedPracticeYears": "string" } ], "authorizedOfficials": [ { "firstName": "string", "middleName": "string", "lastName": "string", "nameCredential": "string", "namePrefix": "string", "nameSuffix": "string", "title": "string", "phoneNumber": "string" } ], "alternateIdentifiers": [ { "value": "string", "type": "string", "state":"string", "issuer":"string" } ], "npis": [ { "npi": "string", "entityTypeCode": "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.
- 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. -
{ "success": boolean, "message": "string", "content": { "linkId": "string", "incomingIdentity": { "sources": [ { "name": "string", "id": "string ", "date": "string" } ], "mergedSourceRecords": [], "names": [ { "first": "string", "middle": "string", "last": "string", "suffix": "string", "prefix": "string", "credential": "string" } ], "authorizedOfficials": [ { "title": "string", "phoneNumber": "string", "namePrefix": "string", "firstName": "string", "middleName": "string", "lastName": "string", "nameSuffix": "string", "nameCredential": "string" } ], "npis": [ { "npi": "string", "entityTypeCode": "string" } ], "license": [ { "number": "string", "state": "string", "taxonomyCode": "string", "licenseEffectiveDate": "string", "licenseExpirationDate": "string", "licenseStatus": "string", "licenseProfessionCode": "string", "licenseProfessionRankCode": "string", "licenseLastUpdateDate": "string", "licenseGrouping": "string", "licenseClassification": "string", "licenseSpecialization": "string" } ], "contactInformation": [ { "address": { "line1": "string", "line2": "string", "city": "string", "state": "string", "postalCode": "string", "addressType": "string", "addressName": "string" }, "phoneList": [ { "number": "string", "type": "string" } ], "faxList": [ { "number": "string", "type": "string" } ] } ], "specialties": [ { "specialtyTaxonomyCode": "string", "grouping": "string", "classification": "string", "specialization": "string" } ], "addresses": [ { "line1": "string", "line2": "string", "city": "string", "state": "string", "postalCode": "string" } ], "detailAddresses": [], "genders": [ "string" ], "emails": [ "string" ], "phoneNumbers": [ { "number": "string", "type": "string" } ], "faxNumbers": [ { "type": "string", "number": "string" } ], "disciplinaryInfo": [ { "warning": "string", "exclusionType": "string" } ], "groupTaxonomies": [ { "groupTaxonomyCode": "string" } ], "medicareInfo": [ { "inPecos": "string", "acceptsMedicare": "string" } ], "education": [ { "medSchool": "string", "gradYear": "string" } ], "locationInfo": [ { "ruralUrbanSuburban": "string", "coloCode": "string" } ], "practiceInfo": [ { "estimatedPracticeYears": "string" } ], "unmergeable": [], "organizationNames": [ { "legalBusinessName": "string", "otherOrgName": "string", "parentOrgName": "string" } ], "alternateIdentifiers": [ { "value": "string", "type": "string", "state": "string", "issuer": "string" } ] }, "linkIdentity": { "linkId": "string", "sources": [ { "name": "string", "id": "string " } ], "mergedSourceRecords": [ { "name": "string", "id": "string" } ], "names": [ { "first": "string", "middle": "string", "last": "string", "suffix": "string", "prefix": "string", "credential": "string" } ], "authorizedOfficials": [ { "title": "string", "phoneNumber": "string", "namePrefix": "string", "firstName": "string", "middleName": "string", "lastName": "string", "nameSuffix": "string", "nameCredential": "string" } ], "npis": [ { "npi": "string", "entityTypeCode": "string" } ], "license": [ { "number": "string", "state": "string", "taxonomyCode": "string" } ], "addresses": [ { "line1": " string", "line2": "string", "city": "string", "state": "string", “postalCode”: “string” } ], "detailAddresses": [], "genders": [ “string” ], "emails": [ "string" ], "phoneNumbers": [ { "number": "string", "type": "string" } ], "faxNumbers": [ { "type": "string", "number": "string" } ], "disciplinaryInfo": [ { "warning": "string", "exclusionType": "string" } ], "groupTaxonomies": [ { "groupTaxonomyCode": "string" } ], "medicareInfo": [ { "inPecos": "string", "acceptsMedicare": "string" } ], "education": [ { "medSchool": "string", "gradYear": "string" } ], "locationInfo": [ { "ruralUrbanSuburban": "string", "coloCode": "string" } ], "practiceInfo": [ { "estimatedPracticeYears": "string" } ], "unmergeable": [], "organizationNames": [ { "legalBusinessName": "string", "otherOrgName": "string", "parentOrgName": "string" } ], "alternateIdentifiers": [ { "state": "string", "type": "string", "value": "string", "issuer": "string" } ] }, "events": [ { "type": "string", "source": { "name": "string", "id": "string" } } ] }, "trackingId": "string", "auditId": UUID, "retryableError": boolean -
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.
{ "success": boolean, "message": "string”, "content": { "linkId": "string", "incomingIdentity": { "sources": [ { "name": "string", "id": "string", “date”: “string” } ], "mergedSourceRecords": [], "names": [ { "first": "string", "middle": "string", "last": "string", "suffix": "string", "prefix": "string", "credential": "string" } ], "authorizedOfficials": [ { "title": "string", "phoneNumber": "string", "namePrefix": "string", "firstName": "string", "middleName": "string", "lastName": "string", "nameSuffix": "string", "nameCredential": "string" } ], "npis": [ { "npi": "string", "entityTypeCode": "string" } ], "licenses": [ { "firstAsserted": "string", "lastAsserted": "string", "license": { "number": "string", "state": "string", "taxonomyCode": "string", "licenseEffectiveDate": "string", "licenseExpirationDate": "string", "licenseStatus": "string", "licenseProfessionCode": "string", "licenseProfessionRankCode": "string", "licenseLastUpdateDate": "string", "licenseGrouping": "string", "licenseClassification": "string", "licenseSpecialization": "string" } } ], "specialties": [ { "firstAsserted": "string", "lastAsserted": "string", "specialty": { "specialtyTaxonomyCode": "string", "grouping": "string", "classification": "string", "specialization": "string" } } ], "contactInformation": [ { "firstAsserted": "string", "lastAsserted": "string", "contactInformation": { "address": { "line1": "string", "line2": "string", "city": "string", "state": "string", "postalCode": "string", "addressType": "string", "addressName": "string" }, "phoneList": [ { "number": "string", "type": "string" } ], "faxList": [ { "type": "string", "number": "string" } ] } } ], "addresses": [ { "line1": "string", "line2": "string", "city": "string", "state": "string", "postalCode": "string" } ], "detailAddresses": [], "genders": [ "string" ], "emails": [ "string" ], "phoneNumbers": [ { "number": "string", "type": "string" } ], "faxNumbers": [ { "type": "string", "number": "string" } ], "disciplinaryInfo": [ { "warning": "string", "exclusionType": "string" } ], "groupTaxonomies": [ { "groupTaxonomyCode": "string" } ], "medicareInfo": [ { "inPecos": "string", "acceptsMedicare": "string" } ], "education": [ { "medSchool": "string", "gradYear": "string" } ], "locationInfo": [ { "ruralUrbanSuburban": "string", "coloCode": "string" } ], "practiceInfo": [ { "estimatedPracticeYears": "string" } ], "unmergeable": [], "organizationNames": [ { "legalBusinessName": "string", "otherOrgName": "string", "parentOrgName": "string" } ], "alternateIdentifiers": [ { "value": "string", "type": "string", "state": "string", "issuer": "string" } ] }, "identityGroupedBySource": [ { "source": { "name": "string", "id": "string" }, "names": [ { "firstAsserted": "string", "lastAsserted": "string", "name": { "first": "string", "middle": "string", "last": "string", "suffix": "string", "prefix": "string", "credential": "string" } } ], "organizationNames": [ { "firstAsserted": "string”, "lastAsserted": "string", "organization": { "legalBusinessName": "string", "otherOrgName": "", "parentOrgName": "string" } } ], "npis": [ { "firstAsserted": "string", "lastAsserted": "string", "npiObject": { "npi": "string", "entityTypeCode": "string" } } ], "licenses": [ { "firstAsserted": "string", "lastAsserted": "string", "license": { "number": "string", "state": "string", "taxonomyCode": "string" } } ], "addresses": [ { "firstAsserted": "string", "lastAsserted": "string", "address": { "line1": " string", "line2": "string", "city": "string", "state": "string", “postalCode”: “string” } } ], "addressDetails": [], "genders": [ { "firstAsserted": "string", "lastAsserted": "string", "gender": "string" } ], "emails": [ { "firstAsserted": "string", "lastAsserted": "string", "email": "string" } ], "phoneNumbers": [ { "firstAsserted": "string", "lastAsserted": "string", "phoneNumber": { "number": "string", "type": "string" } } ], "faxNumbers": [ { "firstAsserted": "string", "lastAsserted": "string", "faxNumber": { "type": "string", "number": "string" } } ], "authorizedOfficials": [ { "firstAsserted": "string", "lastAsserted": "string", "authorizedOfficial": { "title": "string", "phoneNumber": "string", "namePrefix": "string", "firstName": "string", "middleName": "string", "lastName": "string", "nameSuffix": "string", "nameCredential": "string" } } ], "medicareInfo": [ { "firstAsserted": "string", "lastAsserted": "string", "medicareInfo": { "inPecos": "string", "acceptsMedicare": "string" } } ], "disciplinaryInfo": [ { "firstAsserted": "string", "lastAsserted": "string", "disciplinaryInfo": { "warning": "string", "exclusionType": "string" } } ], "groupTaxonomies": [ { "firstAsserted": "string", "lastAsserted": "string", "groupTaxonomy": { "groupTaxonomyCode": "string" } } ], "education": [ { "firstAsserted": "string", "lastAsserted": "string", "education": { "medSchool": "string", "gradYear": "string" } } ], "locationInfo": [ { "firstAsserted": "string", "lastAsserted": "string", "locationInfo": { "ruralUrbanSuburban": "string", "coloCode": "string" } } ], "practiceInfo": [ { "firstAsserted": "string", "lastAsserted": "string", "practiceInfo": { "estimatedPracticeYears": "string" } } ], "alternateIdentifiers": [ { "firstAsserted": "string", "lastAsserted": "string", "alternateIdentifiers": { "state": "string", "type": "string", "value": "string", "issuer": "string" } } ] }, { "mergedSourceRecord": { "name": "string", "id": "string" } } ], "events": [] }, "trackingId": "string", "auditId": UUID, "retryableError": booolean
*For customers with the Address Verification Service, please see the guide for additional data and API information.
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. |
|