postIdentity

  • Web Services
  • API Documentation
  • Provider

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 is known as the Entity Type Code–the entity type code indicates whether a record is an individual practitioner (Entity Type Code of ‘1’) or an organization (Entity Type Code of ‘2’).The combination of Source, Native ID, and Entity Type Code uniquely identifies each of your provider records.  This is important, in part, because you may have updates to the data values for a given provider record in your local source system/application, and you communicate those updates to Provider Data Management using the Source, Native ID, and Entity Type Code.  If Provider Data Management has already seen this Source, Native ID, and Entity Type Code from you before, then it knows you have provided an update to an existing record rather than a new record.  The Source value should be a unique code that represents the source from which a given record came from – it may not contain any whitespace characters in the source code.  Your Source values are added to a configuration system for your instance of Provider Data Management (along with the mapping of which sources can be accessed by which user accounts).

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)

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 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.
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": [ 
            { 
              "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": [ 
            { 
              "taxonomyCode": "string", 
              "number": "string", 
              "state": "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 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 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" 
                    } 
                ], 
                "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 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.

    { 
        "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" 
                    } 
                ], 
                "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 

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 MPI 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.

{
 "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 Link ID.

  • It’s possible that the Source + Native ID submitted in the postIdentity request is the Source + Native ID that receives a Link ID 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 Link ID change. This would happen if two or more pre-existing Link IDs 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 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.

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