HL7 ADT A17 Message: Swap Patients, Structure, Segments & Examples

The HL7 A17 message is an Admit, Discharge, Transfer (ADT) notification used to communicate a swap of two patients' assigned locations. Also known as ADT A17 or Swap Patients, this HL7 Version 2 event allows hospital administration systems, EHRs, and bed management applications to exchange information when two patients switch locations. Unlike an A02 transfer involving one patient, A17 represents a coordinated location exchange involving two patient records. The message contains separate patient and visit information for each participant. This guide explains HL7 ADT A17 structure, sample messages, PID and PV1 mapping, Mirth Connect implementation, acknowledgments, and troubleshooting.

What Is an HL7 ADT A17 Message?

An HL7 ADT A17 message communicates the swapping of two patients between assigned locations. It belongs to the HL7 v2 patient administration message family and supports coordinated patient movement within a healthcare facility. The event may occur when two patients exchange rooms, beds, or other assigned locations as part of hospital operations. Because A17 affects two separate patients and encounters, receiving applications must identify both participants and update their locations consistently. Understanding A17 within the broader HL7 ADT messaging workflow helps integration teams prevent incomplete swaps and incorrect occupancy records.

Purpose of the HL7 A17 Event

A17 communicates a coordinated exchange of assigned patient locations. Receiving applications use the message to update both patients' location records while preserving their individual identities and encounter information.

When Is an ADT A17 Message Generated?

An A17 notification may be generated when two patients exchange assigned beds or rooms. The source patient administration system records the swap and distributes the event to connected applications.

Which Healthcare Systems Receive A17 Messages?

EHRs, bed management platforms, nursing applications, patient tracking systems, and hospital information systems may receive A17 notifications. Each destination processes the exchange according to its supported location management workflow.

How A17 Supports Bed Management

A17 allows connected systems to process two related location changes as one coordinated event. This helps maintain consistent patient assignments and avoid temporary bed occupancy conflicts.

Why Accurate A17 Processing Matters

Incorrect A17 processing can place both patients in the same bed, leave one location unchanged, or associate an encounter with the wrong room. Both participants require accurate matching.

HL7 ADT A17 Message Structure and Segments

An HL7 ADT A17 message uses the segment-based structure defined by HL7 Version 2. Unlike ordinary single-patient ADT events, A17 includes two patient groups, each containing identification and visit information. A typical message begins with MSH and EVN, followed by a PID and PV1 group for the first patient and another PID and PV1 group for the second patient. In HL7 v2.5, the message structure is ADT_A17. Receiving applications should preserve the relationship between each PID and its corresponding PV1 to avoid applying location updates to the wrong patient.

MSH Segment: Message Header

MSH identifies the sending and receiving applications, message timestamp, control identifier, and HL7 version. MSH-9 identifies the A17 swap event and associated ADT_A17 message structure.

EVN Segment: Event Information

EVN records information about the swap event, including its timestamp. Receiving applications may use this metadata for auditing, event sequencing, and troubleshooting location discrepancies.

First PID and PV1 Group

The first patient group identifies one participant in the swap and provides that patient's visit information. Its PV1 segment must remain associated with the corresponding PID.

Second PID and PV1 Group

The second patient group identifies the other participant and provides the associated visit information. Receiving systems should process both groups together rather than as unrelated messages.

Optional Segments in A17 Messages

Additional segments may provide supplementary patient or encounter information, depending on the HL7 version and interface profile. Their presence should follow the agreed implementation specification.

HL7 ADT A17 Message Example With Field Explanation

The following HL7 ADT A17 example illustrates two fictional inpatients exchanging assigned locations. Patient Emma Harris moves to a location previously assigned to patient Michael Reed, while Michael moves to Emma's previous location. The message uses HL7 v2.5 conventions and contains two PID/PV1 groups. MSH-9 identifies the event as ADT^A17^ADT_A17. Each PID-3 identifies a different patient, and each PV1-19 identifies the associated encounter. The assigned locations in the PV1 segments represent the locations after the swap.

Complete HL7 ADT A17 Sample Message

MSH|^~\&|ADT_SYSTEM|HOSPITAL|BED_MGMT|MAIN|20261013130000||ADT^A17^ADT_A17|MSG17001|P|2.5
EVN|A17|20261013125500
PID|1||P170001^^^HOSPITAL^MR||HARRIS^EMMA||19850312|F
PV1|1|I|WARD2^210^B||||1234^SMITH^ANNA||||||||||||V17001
PID|2||P170002^^^HOSPITAL^MR||REED^MICHAEL||19760824|M
PV1|1|I|WARD2^210^A||||5678^JONES^DAVID||||||||||||V17002

All patient information is fictional. Before the swap, Emma occupied WARD2, room 210, bed A, and Michael occupied bed B. The PV1-3 values show their exchanged assignments.

Explore each segment and its key fields:

MSH Segment Explained

MSH identifies ADT_SYSTEM as the sending application and BED_MGMT as the receiver. ADT^A17^ADT_A17 identifies the swap event and message structure, while MSG17001 supports tracking.

EVN Segment Explained

EVN identifies A17 as the event and records its timestamp. Integration teams may use this information to investigate delayed swaps or inconsistencies between patient location histories.

First Patient PID and PV1 Explained

The first PID identifies fictional patient Emma Harris. Its associated PV1 describes Emma's encounter and new assigned location following the coordinated patient swap.

Second Patient PID and PV1 Explained

The second PID identifies fictional patient Michael Reed. Its associated PV1 describes Michael's encounter and new assigned location. Both patient groups must be processed consistently.

PV1-3 and PV1-19 Explained

PV1-3 contains each patient's assigned location, while PV1-19 identifies the associated visit. Together with PID-3, these fields support accurate patient and encounter matching.

Important HL7 ADT A17 Fields and Mapping

Reliable HL7 A17 integration depends on correctly interpreting two separate patient and visit groups within a single message. Important fields include MSH-9 for identifying the swap event, PID-3 for identifying each patient, PV1-3 for assigned locations, and PV1-19 for encounter matching. Receiving systems should validate both participants before changing either location. Developers must also document whether the incoming PV1 values represent the final assignments and how the destination handles atomic updates. Clear HL7 v2 integration rules help prevent incomplete swaps and occupancy conflicts.

MSH-9: Identifying the Swap Event

MSH-9 identifies the A17 event. Integration engines should use this value to apply coordinated two-patient processing rather than treating the message as an ordinary single-patient transfer.

PID-3: Matching Both Patients

Each PID-3 identifies a different patient. Receiving applications should validate both identifiers and assigning authorities before modifying either patient's assigned location.

PV1-3: Mapping Both Assigned Locations

Each PV1-3 identifies the assigned location for its associated patient. The receiving system must preserve the correct PID/PV1 relationship when applying the exchanged assignments.

PV1-19: Identifying Both Encounters

Each PV1-19 identifies the encounter associated with its patient group. Accurate visit matching prevents the swap from changing unrelated encounters or historical location records.

MSH-10: Tracking the Swap Message

MSH-10 identifies the entire A17 notification. Integration teams can use it for acknowledgment correlation, duplicate detection, and auditing the coordinated location exchange.

How HL7 ADT A17 Messages Work in Healthcare Integration

An HL7 ADT A17 workflow begins when a hospital records a swap between two patients' assigned locations. The source patient administration system generates one A17 notification containing both patient groups and their visit information. An integration engine receives the message, validates its structure, and routes it to connected applications. Receiving systems identify both encounters and apply the new location assignments together. If either participant cannot be matched, the destination should follow a controlled exception process rather than completing only part of the swap. Monitoring and acknowledgments support reliable processing.

Step 1: Patient Swap Is Recorded

The hospital records a coordinated exchange of assigned locations between two patients. The source application generates an A17 message containing both patient and visit groups.

Step 2: Validate Both Patient Groups

The integration engine validates the A17 event, two PID segments, two PV1 segments, and required identifiers. Invalid messages should enter a controlled exception workflow.

Step 3: Match Both Patients and Encounters

Receiving applications identify both patients and their associated encounters. Ambiguous or missing matches should be investigated before either location assignment is changed.

Step 4: Apply Coordinated Location Updates

The destination updates both assigned locations according to its supported workflow. Where possible, the changes should be atomic to prevent partial swaps and occupancy conflicts.

Step 5: Acknowledge and Monitor the Swap

The receiving application returns an acknowledgment under the configured HL7 processing mode. Integration teams monitor failures, duplicates, and reconciliation exceptions involving either patient.

How to Implement HL7 ADT A17 Messages Using Mirth Connect

Mirth Connect can receive, validate, transform, and route HL7 ADT A17 messages through configurable integration channels. Unlike ordinary ADT notifications, A17 contains two patient groups that must remain correctly associated with their corresponding visit information. A typical implementation receives the message over MLLP, validates both patients, extracts their encounter and location data, and forwards a coordinated swap request to the destination. Production implementations should address duplicate messages, partial failures, acknowledgment handling, and atomic updates. Mirth Connect development services can support these requirements.

Configure an HL7 Source Connector

Create a Mirth Connect channel with an MLLP listener or another supported transport. Configure the HL7 version, source data type, security controls, and acknowledgment behavior.

Filter ADT A17 Messages

Use a source filter to identify A17 messages. This ensures that ordinary admission, discharge, and transfer events do not enter the two-patient swap processing workflow.

Mirth Connect JavaScript filter:

var messageType =
    msg['MSH']['MSH.9']['MSH.9.1'].toString();

var triggerEvent =
    msg['MSH']['MSH.9']['MSH.9.2'].toString();

return messageType === 'ADT' &&
       triggerEvent === 'A17';

Extract Both Patient and Visit Groups

Use a transformer to extract both patients' identifiers, encounter numbers, and assigned locations. Preserve each PID/PV1 relationship and reject messages with incomplete or duplicate patient information.

Mirth Connect JavaScript transformer:

var patients = [];

var pidSegments = msg['PID'];
var pv1Segments = msg['PV1'];

if (pidSegments.length() !== 2 ||
    pv1Segments.length() !== 2) {
    throw new Error(
        'A17 requires exactly two patient/visit groups'
    );
}

for (var i = 0; i < 2; i++) {
    var pid = pidSegments[i];
    var pv1 = pv1Segments[i];

    var patientId =
        pid['PID.3']['PID.3.1'].toString();

    var assigningAuthority =
        pid['PID.3']['PID.3.4'].toString();

    var visitNumber =
        pv1['PV1.19']['PV1.19.1'].toString();

    var unit =
        pv1['PV1.3']['PV1.3.1'].toString();

    var room =
        pv1['PV1.3']['PV1.3.2'].toString();

    var bed =
        pv1['PV1.3']['PV1.3.3'].toString();

    if (!patientId || !visitNumber ||
        !unit || !room || !bed) {
        throw new Error(
            'Incomplete patient, visit, or location data'
        );
    }

    patients.push({
        patientId: patientId,
        assigningAuthority: assigningAuthority,
        visitNumber: visitNumber,
        assignedLocation: {
            unit: unit,
            room: room,
            bed: bed
        }
    });
}

if (patients[0].patientId === patients[1].patientId &&
    patients[0].assigningAuthority ===
    patients[1].assigningAuthority) {
    throw new Error(
        'Both A17 patient groups identify the same patient'
    );
}

channelMap.put(
    'swapPatients',
    JSON.stringify(patients)
);

Implementation note: The example assumes an HL7 v2 XML representation in which the two PID and PV1 segments are accessible in matching order. Verify the parsed XML and message-group structure in your Mirth Connect version. For production use, account for repeating patient identifiers, assigning authorities, location facilities, and destination-specific visit matching.

Transform A17 Data for Destination Systems

Create a destination payload containing both patient assignments. Preserve the relationship between each patient and the corresponding location to prevent incomplete or incorrect bed exchanges.

Example JSON transformation:

var patients = JSON.parse(
    channelMap.get('swapPatients')
);

var swapRequest = {
    eventType: 'A17',
    action: 'swapPatients',
    messageControlId:
        msg['MSH']['MSH.10']['MSH.10.1'].toString(),
    patients: patients
};

var jsonPayload = JSON.stringify(swapRequest);

channelMap.put('jsonPayload', jsonPayload);

The JSON structure is illustrative. A production destination should validate both assignments and apply the swap as one coordinated transaction where supported.

Validate Atomic Swap Processing

Test successful swaps, missing encounters, occupied destinations, duplicate messages, and partial destination failures. Confirm that neither patient receives an incorrect location if the transaction fails.

HL7 ADT A17 ACK Message Examples and Error Handling

HL7 acknowledgments help sending applications determine whether an A17 swap notification was accepted or rejected under the configured acknowledgment mode. An ACK contains a response code and the original message control identifier. Common application acknowledgment codes include AA for acceptance, AE for application error, and AR for rejection. Because A17 affects two patient encounters, acknowledgment behavior should reflect whether the receiving application successfully accepted the coordinated operation. An ACK alone does not necessarily prove that every downstream bed management system has completed its update.

Successful ACK Response: AA

An AA acknowledgment indicates application-level acceptance under the configured acknowledgment mode. MSA-2 identifies the original A17 notification, allowing the sender to correlate the response.

MSH|^~\&|BED_MGMT|MAIN|ADT_SYSTEM|HOSPITAL|20261013130001||ACK^A17^ACK|ACK17001|P|2.5
MSA|AA|MSG17001

Application Error Response: AE

An AE acknowledgment indicates an application processing error. Unknown patient identifiers, missing encounters, or conflicting bed assignments may prevent the receiving system from completing the swap.

MSH|^~\&|BED_MGMT|MAIN|ADT_SYSTEM|HOSPITAL|20261013130002||ACK^A17^ACK|ACK17002|P|2.5
MSA|AE|MSG17001
ERR|||204^Unknown Key Identifier^HL70357|E

Application Rejection Response: AR

An AR acknowledgment indicates that the receiving application rejected the swap notification. The sender should investigate the rejection before correcting or retransmitting the message.

MSH|^~\&|BED_MGMT|MAIN|ADT_SYSTEM|HOSPITAL|20261013130003||ACK^A17^ACK|ACK17003|P|2.5
MSA|AR|MSG17001

Correlate ACK Responses With the Swap Event

MSA-2 identifies the original A17 message control identifier. Integration engines use this value to associate acknowledgment responses with the complete two-patient swap.

Handle Partial Failures and Retries

If one patient update succeeds while the other fails, the destination must reconcile the inconsistent state. Retries should be idempotent and should not repeat completed swaps.

Common HL7 ADT A17 Integration Errors and Troubleshooting

HL7 A17 integration problems often involve incorrect PID/PV1 pairing, missing encounter identifiers, duplicate swaps, and conflicts between current and destination bed assignments. Because the message affects two patients, a mapping error can create inconsistencies in multiple records. Some receiving applications may not support A17 directly and require an agreed alternative workflow. Troubleshooting should examine both patient groups, original location assignments, acknowledgment responses, and destination transaction logs. Consistent HL7 parsing and data mapping helps identify problems before they affect production bed management.

Incorrect PID and PV1 Association

A transformer may associate the first patient's PID with the second patient's PV1. Validate message grouping and segment order before applying location changes.

One Patient Is Not Found

The destination may identify one patient but fail to locate the other encounter. Reject or defer the complete swap rather than applying only one location update.

Duplicate A17 Notifications

Repeated swap notifications may cause a receiving application to reverse or reapply an already completed exchange. Implement idempotency using message identifiers and encounter state.

Conflicting Bed Assignments

The destination may reject a swap because one location is occupied by an unexpected patient. Validate current assignments and resolve discrepancies before processing.

Destination Does Not Support A17

Some healthcare applications do not implement two-patient swap events. Determine whether the vendor supports an equivalent coordinated workflow before attempting conversion into individual transfers.

HL7 ADT A17 vs A02, A12, A15, and A26

HL7 ADT events describe different patient movement workflows. A17 represents a coordinated swap involving two patients, while A02 communicates an actual transfer involving one patient. A12 cancels a previously recorded transfer. A15 communicates a pending transfer, and A26 cancels that pending movement. Although these events may contain similar patient and visit information, their processing requirements differ. Receiving systems should use event-specific rules to preserve accurate location histories, avoid duplicate movements, and prevent partial updates across multiple patient encounters.

A17 vs A02: Swap and Individual Transfer

A02 communicates movement of one patient, while A17 coordinates the exchange of two patients. A17 requires both patient groups to be matched and processed consistently.

A17 vs A12: Swap and Transfer Cancellation

A12 cancels a previously recorded transfer, while A17 communicates a coordinated exchange of patient locations. These events require different validation and destination update logic.

A17 vs A15: Actual Swap and Pending Movement

A15 communicates an anticipated transfer, while A17 represents a coordinated swap of assigned locations. Receiving systems should not interpret A15 as confirmation of movement.

A17 vs A26: Swap and Pending Transfer Cancellation

A26 cancels a pending transfer, while A17 communicates a location exchange between two patients. Their encounter and bed management effects are different.

Best Practices for Reliable HL7 A17 Integration

Reliable HL7 A17 integration requires accurate patient identification, visit matching, location validation, and coordinated transaction handling. Healthcare organizations should document how receiving applications interpret the two patient groups and whether the destination supports atomic location updates. Interfaces should define duplicate detection, acknowledgment behavior, rollback procedures, and reconciliation requirements. Because A17 messages contain information about two patients, secure transmission and controlled logging are particularly important. Combining validation, monitoring, and consistent exception handling helps maintain accurate bed assignments across connected healthcare systems.

Validate Both Patients Before Processing

Confirm both patient identifiers, assigning authorities, and encounter numbers before modifying either location. Reject ambiguous matches to prevent incorrect assignments.

Preserve PID and PV1 Group Relationships

Ensure each patient identifier remains associated with its corresponding visit and location. Test parsing behavior with multiple patient groups and optional segments.

Apply Atomic Location Updates Where Possible

Update both patient assignments in one coordinated transaction when supported. If atomic updates are unavailable, establish rollback and reconciliation procedures for partial failures.

Prevent Duplicate Swap Processing

Track processed message identifiers and current encounter states. Repeated A17 notifications should not reverse or duplicate a previously completed swap.

Monitor Location Conflicts and Exceptions

Track rejected swaps, occupancy conflicts, missing encounters, and inconsistent assignments. Establish alerts and reconciliation procedures for unresolved two-patient location changes.

Frequently Asked Questions About HL7 ADT A17 Messages

HL7 A17 integration involves two-patient identification, location exchange, and coordinated encounter updates. Healthcare developers and IT teams often need to understand how A17 differs from a normal transfer, why two PID and PV1 groups appear, and how to handle partial failures. The following questions address common technical concerns using HL7 v2.5 conventions. Actual processing behavior depends on the sending application, receiving system, and agreed interface implementation guide.

Need Help With HL7 ADT A17 Integration?

Reliable patient swap messaging helps healthcare organizations maintain accurate bed assignments when two patients exchange locations. Taction Software supports HL7 interface development, Mirth Connect configuration, patient and encounter matching, and bed management integration. Our engineers can help organizations implement two-patient message parsing, coordinated location updates, duplicate prevention, and exception handling. Whether you are connecting an EHR to a bed management platform or improving existing ADT interfaces, accurate A17 processing supports consistent patient movement records across connected healthcare applications.

Custom HL7 Patient Swap Interfaces

We develop HL7 A17 interfaces based on source and destination requirements. Implementation includes two-patient validation, encounter matching, location mapping, and acknowledgment handling.

Mirth Connect Channel Development

Our engineers configure Mirth Connect channels for patient swap notifications, including message filtering, JavaScript transformations, destination connectivity, and exception handling.

Bed Management and Location Reconciliation

We help organizations maintain consistent patient location assignments through coordinated updates, occupancy validation, and reconciliation procedures for partial failures.

Production Monitoring and Support

We support HL7 interfaces through monitoring, failure alerts, mapping updates, and recovery procedures. These services help maintain dependable patient movement messaging as healthcare applications evolve.

Need help with HL7 patient swap integration? Explore our HL7 interface messaging services to discuss your requirements.