Add or Update Record

POST /mpi/v1/record/{source}/{identifier}

Adds a new record or updates a previously created one. Returns the record’s assigned person ID, along with any changes resulting from the addition or update.

Note
Partial updates are not supported; an update will completely replace the existing record. See Understanding Matching for details.

Contents

Path Parameters
Body Data
Response Data

Path Parameters

source string

The system from which the record demographics were sourced.

identifier string

The unique identifier of the record within the source. This will be stored directly in the Identity service (not hashed or encrypted), so consider what kind of identifiers are suitable to your use case.

Body Data

firstName string

middleName string

lastName string

maidenName string

gender string

A HL7 administrative gender category code (i.e., male, female, other, unknown).

race string

A HL7 race category code (e.g., 2054-5 means “Black or African American”).

homePhoneNumber string

cellPhoneNumber string

email string

dob string

Date of birth in yyyy/mm/dd or yyyy-mm-dd format.

street string

Street address.

city string

state string

Two-letter state abbreviation.

zipCode string

Postal or Zip code.

mrn string

A medical record number, often used by electronic medical record systems.

hcid string

A Health Card Identifier, such as an enrollee ID on an insurance plan.

ssn string

Either the full 9 or last 4 digits of a Social Security Number.

medicaidId string

The Medicaid ID number.

medicareBeneficiaryIdentifier string

The Medicare Beneficiary Identifier (MBI).

Response Data

matchedPerson object

The primary person matched in this operation.

+ Child Fields

matchedPerson.id string

The stable identifier for this person used across records (“Person ID”).

matchedPerson.records collection

The constituent records that represent this person.

+ Child Fields

matchedPerson.records.source string

A source system with an internal means of identifying individuals.

matchedPerson.records.identifier string

matchedPerson.version integer

As records are added or removed, this version number will be incremented.

matchedPerson.status object

+ Child Fields

matchedPerson.status.code string

One of: Active or Retired. A record is retired when the original record has been superceded by new record(s).

matchedPerson.status.supercededBy collection<string

If the person’s constituent records were merged into another person, this will contain the id for that person.

If the person’s constituent records were split into two or more persons, this will contain the ids for those persons.

changedPersons collection

Other persons that were changed in the process of adding/updating this record.

+ Child Fields

changedPersons.id string

The stable identifier for this person used across records (“Person ID”).

changedPersons.records collection

The constituent records that represent this person.

+ Child Fields

changedPersons.records.source string

A source system with an internal means of identifying individuals.

changedPersons.records.identifier string

changedPersons.version integer

As records are added or removed, this version number will be incremented.

changedPersons.status object

+ Child Fields

changedPersons.status.code string

One of: Active or Retired. A record is retired when the original record has been superceded by new record(s).

changedPersons.status.supercededBy collection<string

If the person’s constituent records were merged into another person, this will contain the id for that person.

If the person’s constituent records were split into two or more persons, this will contain the ids for those persons.

advisories object

Contains advisory messages about the operation.

+ Child Fields

advisories.invalidDemographicFields collection

A list of demographic field names that were not used for matching because they contained invalid values.