MVI request XML

Last Updated: May 6, 2025

This page describes a sample request for the Master Veteran Index (MVI) database. MVI is the authoritative identity service within the VA, establishing, maintaining, and synchronizing identities for VA clients, Veterans, and beneficiaries.

MVI was renamed Master Person Index (MPI) in April 2020. For more information on how to use MPI visit: Master Person Index (MPI).

Overview

The MVI provides the access point mechanism for linking patient's information to enable an enterprise-wide view of patient information. MVI uniquely identifies all active patients who have been admitted, treated, or registered in any VHA facility, and assigns a unique identifier to the patient. The MVI facilitates the sharing of health information, resulting in coordinated and integrated health care for Veterans.

The MVI also establishes a unique enterprise identifier called an Integration Control Number (ICN) for each of the VA unique person records. On Vets-API when identity information is required, but not available, the MVI lookup can be used to get that information. MVI uses SOAP (Simple Object Access Protocol) for exchanging structured data with other services. MVI uses 'correlation ids' as a foreign key to reference external services.

Example Request

CODE

<env:Envelope xmlns:soapenc="http://schemas.xmlsoap.org/soap/encoding/" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:env="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
    <env:Header/>
    <env:Body>
        <idm:PRPA_IN201305UV02
            xmlns:idm="http://vaww.oed.oit.va.gov"
            xmlns:xsi="http://www.w3.org/2001/XMLSchema‐instance"
            xsi:schemaLocation="urn:hl7‐org:v3 ../../schema/HL7V3/NE2008/multicacheschemas/PRPA_IN201305UV02.xsd"
            xmlns="urn:hl7‐org:v3"
            ITSVersion="XML_1.0">
            <id root="1.2.840.114350.1.13.0.1.7.1.1" extension="200VGOV-e3842012-240d-4df2-8726-45a3c52dc94f"/>
            <creationTime value="20161021184458"/>
            <versionCode code="3.0"/>
            <interactionId root="2.16.840.1.113883.1.6" extension="PRPA_IN201305UV02"/>
            <processingCode code="T"/>
            <processingModeCode code="T"/>
            <acceptAckCode code="AL"/>
            <receiver typeCode="RCV">
                <device classCode="DEV" determinerCode="INSTANCE">
                    <id root="1.2.840.114350.1.13.999.234" extension="200M"/>
                </device>
            </receiver>
            <sender typeCode="SND">
                <device classCode="DEV" determinerCode="INSTANCE">
                    <id root="2.16.840.1.113883.4.349" extension="200VGOV"/>
                </device>
            </sender>
            <controlActProcess classCode="CACT" moodCode="EVN">
                <code code="PRPA_TE201305UV02" codeSystem="2.16.840.1.113883.1.6"/>
                <dataEnterer typeCode="ENT" contextControlCode="AP">
                    <assignedPerson classCode="ASSIGNED">
                        <id extension="796127160" root="2.16.840.1.113883.777.999"/>
                        <assignedPerson classCode="PSN" determinerCode="INSTANCE">
                            <name>
                                <given>KENT</given>
                                <given>M</given>
                                <family>WARREN</family>
                            </name>
                        </assignedPerson>
                    </assignedPerson>
                </dataEnterer>
                <queryByParameter>
                    <queryId root="1.2.840.114350.1.13.28.1.18.5.999" extension="18204"/>
                    <statusCode code="new"/>
                    <modifyCode code="MVI.COMP1"/>
                    <initialQuantity value="1"/>
                    <parameterList>
                        <livingSubjectAdministrativeGender>
                            <value code="M"/>
                            <semanticsText>Gender</semanticsText>
                        </livingSubjectAdministrativeGender>
                        <livingSubjectBirthTime>
                            <value value="19360714"/>
                            <semanticsText>Date of Birth</semanticsText>
                        </livingSubjectBirthTime>
                        <livingSubjectId>
                            <value root="2.16.840.1.113883.4.1" extension="796127160"/>
                            <semanticsText>SSN</semanticsText>
                        </livingSubjectId>
                        <livingSubjectName>
                            <value use="L">
                                <given>KENT</given>
                                <given>M</given>
                                <family>WARREN</family>
                            </value>
                            <semanticsText>Legal Name</semanticsText>
                        </livingSubjectName>
                    </parameterList>
                </queryByParameter>
            </controlActProcess>
        </idm:PRPA_IN201305UV02>
    </env:Body>
</env:Envelope>

Full List of MVI Attributes

given_names
family_name
suffix
gender
birth_date
ssn
address
home_phone
full_mvi_ids
icn
mhv_ids
active_mhv_ids
edipi
participant_id
vha_facility_ids
sec_id
birls_id
vet360_id
historical_icns
icn_with_aaid
mhv_correlation_id

Glossary for Attributes

icn - An ICN (Integration Control Number - generated by the Master Patient Index) MVI correlation ID [String]
edipi - A DOD EDIPI (Electronic Data Interchange Personal Identifier) MVI correlation ID
birls_id - A BIRLS (Beneficiary Identification and Records Locator System) MVI correlation id. [String]
vet360_id - A Vet360 Correlation ID
historical_icns - A list of ICN's that the user has been identitfied by historically [Array[String]]
icn_with_aaid - An ICN (Integration Control Number - generated by the Master Patient Index) MVI correlation ID combined with its Assigning Authority ID [String] For example: '12345678901234567^NI^200M^USVHA^P'
mhv_correlation_id - The first active MHV (My HealtheVet) MVI correlation id [String]
participant_id - the VBA (Veterans Benefits Administration) Corp ID

ID Statuses

IDSTATUS can be one of the following statuses:

P - Permanent ICNs
A - Active Correlations
H - Deprecated due to local merge. This is a value identified for correlations including EDIPI when the identifier has been deprecated/associated to another active ID.
L – Local merge pending. This is used to support the marking of active records as pending a merge, so that systems that have a large number of local dups can apply business rules to highlight 1 active and mark the others if applicable with this new status. This will allow business processes to utilize the 1 active (implemented in version 4.1 or higher)
D - Deprecated from a Duplicate
M - Deprecated from a Mismatch
U - Deprecated from an Unlink
H - Deprecated from a Local Merge
PCE - Pending Cat Edit correlations

ID Format

ID^TYPE^SOURCE^ISSUER^IDSTATUS

Sample System Identifiers

ICN ID:

CODE

<id root="2.16.840.1.113883.4.349" extension="1008533405V377263^NI^200M^USVHA"/> 
OR
<id root="2.16.840.1.113883.4.349" extension="1008533405V377263^NI”/>

 Sec ID:

CODE

<id root="2.16.840.1.113883.4.349" extension="1000020007^PN^200PROV^USDVA"/>

DoD EDIPI ID:

CODE

<id root="2.16.840.1.113883.3.42.10001.100001.12" extension="1234567890^NI^200DOD^USDOD"/>

 BIRLS ID:

CODE

<id root="2.16.840.1.113883.4.349" extension="123456^PI^200BRLS^USVBA "/>

MHV User ID:

CODE

<id root="2.16.840.1.113883.4.349" extension="123456^PI^200MHV^USVHA"/>

Help and feedback

Suggest content changes to this page.
Submit new Platform Website content.
Get help from the Platform Support Team in Slack.
Submit a feature idea to the Platform.