FHIR CI-Build
AdministrationThis is the Continuous Integration Build of FHIR (will be incorrect/inconsistent at times).
See the Directory of published versions 
| Patient Administration Work Group | Maturity Level: 0 | Trial Use | Compartments: N/A |
The merge operation is used to request two encounter resources be merged. One of the two encounter is identified as the source and one as the target. The target is the remaining encounter resource (survivor), the source will be marked as inactive (or in some systems deleted).
The source-encounter resource will be updated to add a new link reference to the target-encounter resource (link-type=replaced-by in the record-linkage extension), and also update the status to inactive (unless the resource was deleted)
The target-encounter resource will be updated to add a new link reference to the source-encounter resource (link-type=replaces in the record-linkage extension) - and must be included in the result-encounter parameter if used (if the source encounter is deleted, then this link is not required).
The canonical URL for this operation definition is
http://hl7.org/fhir/OperationDefinition/Encounter-merge
Formal Definition (as a OperationDefinition).
URL: [base]/Encounter/$merge
This is not an idempotent operation
| In Parameters: | ||||||
| Name | Scope | Cardinality | Type | Binding | Profile | Documentation |
| source-encounter | 0..1 | Reference(Encounter) | A direct resource reference to the source encounter resource (this may include an identifier). | |||
| source-encounter-identifier | 0..* | Identifier | When source-encounter-identifiers are provided, the server is expected to perform an internal lookup to identify the source encounter. The server SHALL reject the request if the provided identifiers do not resolve to a single encounter record. This resolution MAY occur asynchronously, for example, as part of a review by a user. | |||
| target-encounter | 0..1 | Reference(Encounter) | A direct resource reference to the target encounter resource. This is the surviving encounter resource, the target for the merge. | |||
| target-encounter-identifier | 0..* | Identifier | When target-encounter-identifiers are provided, the server is expected to perform an internal lookup to identify the target encounter record. The server SHALL reject the request if the provided identifiers do not resolve to a single encounter record. This resolution MAY occur asynchronously, for example, as part of a review by a user. | |||
| result-encounter | 0..1 | Encounter | The details of the Encounter resource that is expected to be updated to complete with and must have the same encounter.id and provided identifiers included. This resource MUST have the record-linkage extension with a link=replaces referencing the source encounter resource. It will be used to perform an update on the target encounter resource. In the absence of this parameter the servers should copy all identifiers from the source encounter into the target encounter, and include the record-linkage extension (as shown in the example below). This is often used when properties from the source encounter are desired to be included in the target resource. The receiving system may also apply other internal business rules onto the merge which may make the resource different from what is provided here. | |||
| preview | 0..1 | boolean | If this is set to true then the merge will not be actually performed; an OperationOutcome will be returned in the Parameters response that will indicate that no merge has occurred and may include other diagnostic info if desired, such as the scale of the merge. e.g. Issue.details.text "Preview only Encounter merge - no issues detected" e.g. Issue.diagnostics "Merge would update: 10 years of content or 120 resources" The resulting target encounter resource will also be returned in the result. | |||
| Out Parameters: | ||||||
| Name | Scope | Cardinality | Type | Binding | Profile | Documentation |
| return | 1..1 | Parameters | The status of the response will be one of:
The Parameters resource will include:
Note: as this is the only out parameter, it is a resource, and it has the name 'return', the result of this operation is returned directly as a resource Note: as this is the only out parameter, it is a resource, and it has the name 'return', the result of this operation is returned directly as a resource | |||
There must be exactly 1 source encounter, which may be identified by either the source-encounter or source-encounter-identifier parameters. Similarly, there must be exactly 1 target encounter, identified by either the target-encounter or target-encounter-identifier parameters. In both cases, either a reference to the encounter or a list of identifiers that can be used to identify the encounter may be provided, but not both.
The result-encounter.id must be the same as the target encounter reference (if the encounter reference is provided as an input parameter).
If a client needs the server to create a new encounter merged from the 2 encounter resources, the client should create a new encounter record and then call the merge operation to merge each source encounter resource into the newly created encounter resource.
A server may decide to delete the source record, but this is not defined by the standard merge operation, and if this occurs then the target encounter's link property will remain unchanged.
The merge operation will have multiple stages, and some of these may take additional time for processing and thus be done asynchronously.
| Stage | Description |
| Preview Merge | (Optional) This is a call to the operation (with preview=true) that simply checks for potential errors and warnings, without committing any changes. This might not be able to capture all possible causes of errors that could be encountered during the processing of the data patching. The returned Encounter resource is a preview only and has not been committed. Hence the version number and last_modified date would be cleared/absent. |
| Initiate Merge | This stage processes the input parameters checking for errors/warnings and prepares to make changes to the encounter resources. If the system is able to complete the processing of all reference data to the target encounter, then the merge process may complete immediately where no Task is needed and the data processing stage occurs as part of the Initiate Merge action. Otherwise a Task for tracking would be created and monitor the progress of the merge. |
| Data Processing | The REST operation may have returned, and processing is ongoing to patch any other resource that references the source encounter to reference the target encounter. This may take a considerable period of time in some systems where the volume of records being updated is large. The source encounter record will be marked as inactive, and add the link property to the target encounter (except where systems delete the record) |
| Completed (or failed) | All data processing is complete, and the Task is marked as completed (maybe with errors) |
During the Data Processing stage any of the related encounter resources (source, target, and result) and any resources referencing any of these encounters may be indeterminate until the merge processing operation completes. These resources may be in the process of being changed or deleted, or having references updated, and there is no implied sequence for these updates to be made. There is also no implication that these changes are happening within a single transaction. Data consumers should wait until the merge process completes before querying for data about any of the relevant encounters.
Note: Some servers may also update the inactive source encounter resource to remove most of the data to make it more clear that the resource should not be used, and the record-linkage extension is the key information.
Note: Systems may do any other internal checks or business rule validation when preparing for or performing a merge.
The server may also migrate identifiers (and properties) from the source encounter at its discretion, and choose to mark these as old or not.
Note to Implementers:
The handling of identifiers is different to the corresponding description at patient merge, since Encounters probably do not contain any important business identifiers like Patient does. Please provide feedback if this assumption should not be correct.
The merge data processing SHALL update all references that refer to the source encounter to reference the target encounter.
While updating resources that reference the source encounter, ensure that the target encounter link value isn't also accidentally updated (don't make it point at itself).
A Provenance resource SHOULD be created that references the source and target encounter resources (or just the target-resource if the source was deleted, or the source encounter's old identifier) indicating that the merge has occurred (see example below).
A Provenance resource MAY be created to link all of the resources that referenced the source encounter that could then provide information to a potential un-merge operation.
Note: Some resources that have been updated as a result of the merge, such as AuditEvent, Provenance, may have been digitally signed, and this change would invalidate the signature. There may be other reasons impacting the updates that should be considered, further feedback on this specific use case is required.
Note to Implementers:
Are there other implications of these reference updates that should be identified relating to versions - (such as where a version specific reference was included)?
Note: While this processing is occurring, if a client requests clinical data for either source or target encounter, an OperationOutcome with an informative message MAY be included in the resulting bundle indicating this processing is ongoing.
Note to Implementers:
Considering updating http://hl7.org/fhir/valueset-issue-type.html
A GET on the source Encounter resource ID (e.g. GET [base]/Encounter/enc01) will return either:
Note: Security implications such as those from SMART tokens could restrict access here.
When performing a SEARCH by the source encounter resource ID return (e.g. GET [base]/Encounter?_id=enc01):
(often used as a substitute for direct GET when doing _include for the managing org/general practitioner)
Accessing the Encounter $everything operation on the source encounter resource (now marked as inactive) will return an OperationOutcome and http status of 400 Bad Request. The error message should inform that the encounter has been merged and should follow the Encounter record-linkage extension to access the $everything content.
Note to Implementers:
Considering updating the http://hl7.org/fhir/valueset-issue-type.html
Searching content (e.g. Observations) based on Encounter ID:
Observation?encounter=Encounter/enc01 would return a 200 Ok Bundle with no results (as all have been moved to Encounter/enc02), an OperationOutcome may be included indicating that the encounter was merged into encounter xxxObservation?encounter=Encounter/enc02 would return all the data that is referencing enc02, and all the data that was referencing enc01 (which was updated by the merge operation to reference enc02)Searching content (e.g. Observations) based on Encounter ID and time ranges:
Observation?encounter=Encounter/enc02 (initial client call at start of year, gets all encounter obs)Observation?encounter=Encounter/enc02&_lastupdated=ge2019-03 (client calls at start of march to detect any new encounter obs)Observation?encounter=Encounter/enc02&_lastupdated=ge2019-06 (client calls at start of june to detect any new encounter obs, but misses all the enc01 observations prior to June)In the case where a client needs to be aware of all relevant resources, including those that were added to an encounter as the result of a merge, the client would need to be notified via some channel other than a RESTful polling process that a merge has occurred. There are a few options for how a client may detect that a fresh retrieval of all content for an encounter may be needed:
Note to Implementers:
Creating/Updating content (e.g. Observations) that reference the source encounter ID (feedback on this required):
- 422 Unprocessable Entity with an OperationOutcome indicating that the encounter referenced was merged into encounter xxx (this is also the existing behavior if the encounter resource was deleted)
- 201 Created if the service is able to automatically process the request and reallocate, this could occur during the merge data processing stage, otherwise the above code should be returned
The indication that a merge has been completed can be notified through several ways:
These notifications can be sent to other downstream systems, partners, or other applications (including EMPIs). An EMPI could expose the merge operation, and therefore be a notification sender.
Consideration should be taken to ensure that the correct data is acted on.
The downstream systems might not have all identifiers that the notifying system has, the notifier may be configured to know what "types" of identifiers should be propagated to which systems.
Note: When using the identifier parameters (rather than id) you should be using the same assigner (which in the example above would be the PAS/ADT or clinical system), this may be configured in the sending notification system, such as an EMPI based on local business rules.
Subscriptions on merges are most likely to be used by applications connecting directly to the system. Many use cases could consider using FHIR Messaging (or other messaging e.g. v2 messages) to communicate the merge occurred.
Note to Implementers:
Interaction with the Subscription v2 resources requires additional review and implementer feedback considering:
- What can be used as triggers for the subscription:
- Encounter update with new link values
- Provenance(s) as an event
- operation itself as an event (the Task resource, although that might not exist, so just a pre-defined topic)
- Will all the data that is patched over to the target encounter ID be notified:
- Systems might not notify that the content was changed, and rely on the merge notification to advise if required
- Also note the Client data refresh notification discussion above
The FHIR Request Message should be a Bundle with:
| Resource | Cardinality | Description |
| MessageHeader | 1..1 | The Messaging header The focus of the message will be the Parameters resource. |
| Parameters | 1..1 | The same Parameters object that would be passed to the $merge operation. |
| Encounter (source) | 0..1 | Source Encounter resource (may not be complete, but should have enough to be able to identify the source record) This is the Encounter resource that will be marked as inactive after the merge. |
| Encounter (target) | 0..1 | Target Encounter resource (may not be complete, but should have enough to be able to identify the target record) This is the Encounter resource that will remain active after the merge operation is complete. |
The FHIR Response Message should be a bundle with:
| Resource | Cardinality | Description |
| MessageHeader | 1..1 | The Messaging header The focus of the message will be the Parameters resource. |
| Parameters | 1..1 | The parameters resource that was included in the request. |
| OperationOutcome | 1..1 | The results of the merge operation. |
| Encounter | 0..1 | The resulting Encounter resource from the merge operation. (required when the result was a successful operation) |
| AuditEvent | 0..1 | An operation event that includes the full details of the operation, including references to all the resources that were updated as a result of the merge. |
Any errors will be reported with an OperationOutcome resource and could include:
Issue |
Description |
Http Status |
|---|---|---|
| err: Same resource | The Source and Target matching resulted in the same FHIR Encounter resource, likely already merged. | 422 Unprocessable Entity |
| err: Missing Source Parameters | There are no source Encounter parameters, please include either a source-encounter, source-encounter-identifier parameter (or both) | Bad Request |
| err: Missing Target Parameters | There are no target Encounter parameters, please include either a target-encounter, target-encounter-identifier parameter (or both) | Bad Request |
| err: Target Encounter Id mismatch | The target Encounter id does not match the Encounter id in the result-encounter resource |
Bad Request |
| err: Source Encounter not found | The source Encounter was not found based on the provided parameters | 422 Unprocessable Entity |
| err: Target Encounter not found | The target Encounter was not found based on the provided parameters | 422 Unprocessable Entity |
| err: Target/Source not duplicates | Attempt to merge 2 records that are known to not be duplicates of each other. (Previous manual marking of the resources was done, and will need to be removed before retrying) |
422 Unprocessable Entity |
| err: Target Encounter already merged | The Target Encounter resource was previously merged into another encounter record, and is not a suitable target for merging. | 422 Unprocessable Entity |
| err: Target Encounter inactive | The Target Encounter resource is marked as inactive Note: Further feedback on this case? |
422 Unprocessable Entity |
| info: Target Encounter updated | Additional notes on what happened to the target Encounter resource on update, such as if fields weren't updated as requested due to internal business rules etc | - |
| info: Update summary | Other notes that are included reporting on what changed, such as how many resources were/may be effected | - |
| warn: Recommend reverse merge | The source resource is much larger than the target resource (in terms of resources that reference it) and recommend that the merge occur in the other direction Note: This would likely be returned/evaluated during the preview stage/mode if implemented. |
- |
| info: Encounter merge in progress | Note: This is applicable to other search operations on resources referencing these Encounter resource(s), and not specifically the merge operation itself The encounter record referenced by these records is currently being merged to/from another Encounter resource. Data may be incomplete, or inconsistent. (this MAY be returned during a clinical data search using the Encounter ID as a search parameter) |
- |
Note to Implementers:
Seeking implementer feedback on safety checklist items to include.
Request: Encounter merge using encounter reference with identifiers and providing an explicit resulting resource:
POST /open/Encounter/$merge
[some headers]
POST: [base]/Encounter/$merge
<Parameters xmlns="http://hl7.org/fhir">
<parameter>
<name value="source-encounter" />
<valueReference>
<reference value="Encounter/enc01" />
<identifier>
<use value="official" />
<system value="urn:oid:2.16.840.1.113883.3.72.5.9.1" />
<value value="1000000001" />
<assigner>
<display value="Hospital A" />
</assigner>
</identifier>
</valueReference>
</parameter>
<parameter>
<name value="target-encounter" />
<valueReference>
<reference value="Encounter/enc02" />
<identifier>
<use value="official" />
<system value="urn:oid:2.16.840.1.113883.3.72.5.9.1" />
<value value="1000000002" />
<assigner>
<display value="Hospital A" />
</assigner>
</identifier>
</valueReference>
</parameter>
<parameter>
<name value="result-encounter" />
<resource>
<Encounter xmlns="http://hl7.org/fhir">
<id value="enc02" />
<identifier>
<use value="official" />
<system value="http://www.hospital-a/localid" />
<value value="1000000002" />
<assigner>
<display value="Hospital A" />
</assigner>
</identifier>
<identifier>
<use value="old" />
<system value="http://www.hospital-a/localid" />
<value value="1000000001" />
<assigner>
<display value="Hospital A" />
</assigner>
</identifier>
<status value="completed"/>
<class>
<coding>
<system value="http://terminology.hl7.org/CodeSystem/v3-ActCode"/>
<code value="AMB"/>
<display value="ambulatory"/>
</coding>
</class>
<priority>
<coding>
<system value="http://snomed.info/sct"/>
<code value="17621005"/>
<display value="Normal"/>
</coding>
</priority>
<type>
<coding>
<system value="http://snomed.info/sct"/>
<code value="11429006"/>
<display value="Consultation"/>
</coding>
</type>
<subject>
<reference value="Patient/f201"/>
<display value="Roel"/>
</subject>
<serviceProvider>
<reference value="Organization/f201"/>
</serviceProvider>
<participant>
<actor>
<reference value="Practitioner/f201"/>
</actor>
</participant>
<reason>
<value>
<concept>
<text value="The patient had fever peaks over the last couple of days. He is worried about these
peaks."/>
</concept>
</value>
</reason>
</Encounter>
</resource>
</parameter>
</Parameters>
Response: Results from the merge request above
HTTP/1.1 200 OK
[other headers]
<Parameters xmlns="http://hl7.org/fhir">
<parameter>
<name value="input" />
<resource>
<Parameters>
<parameter>
<name value="source-encounter" />
<valueReference>
<reference value="Encounter/enc01" />
<identifier>
<use value="official" />
<system value="urn:oid:2.16.840.1.113883.3.72.5.9.1" />
<value value="1000000001" />
<assigner>
<display value="Hospital A" />
</assigner>
</identifier>
</valueReference>
</parameter>
<parameter>
<name value="target-encounter" />
<valueReference>
<reference value="Encounter/enc02" />
<identifier>
<use value="official" />
<system value="urn:oid:2.16.840.1.113883.3.72.5.9.1" />
<value value="1000000002" />
<assigner>
<display value="Hospital A" />
</assigner>
</identifier>
</valueReference>
</parameter>
<parameter>
<name value="result-encounter" />
<resource>
<Encounter xmlns="http://hl7.org/fhir">
<id value="enc02" />
<identifier>
<use value="official" />
<system value="http://www.hospital-a/localid" />
<value value="1000000002" />
<assigner>
<display value="Hospital A" />
</assigner>
</identifier>
<identifier>
<use value="old" />
<system value="http://www.hospital-a/localid" />
<value value="1000000001" />
<assigner>
<display value="Hospital A" />
</assigner>
</identifier>
<status value="completed"/>
<class>
<coding>
<system value="http://terminology.hl7.org/CodeSystem/v3-ActCode"/>
<code value="AMB"/>
<display value="ambulatory"/>
</coding>
</class>
<priority>
<coding>
<system value="http://snomed.info/sct"/>
<code value="17621005"/>
<display value="Normal"/>
</coding>
</priority>
<type>
<coding>
<system value="http://snomed.info/sct"/>
<code value="11429006"/>
<display value="Consultation"/>
</coding>
</type>
<subject>
<reference value="Patient/f201"/>
<display value="Roel"/>
</subject>
<serviceProvider>
<reference value="Organization/f201"/>
</serviceProvider>
<participant>
<actor>
<reference value="Practitioner/f201"/>
</actor>
</participant>
<reason>
<value>
<concept>
<text value="The patient had fever peaks over the last couple of days. He is worried about these
peaks."/>
</concept>
</value>
</reason>
</Encounter>
</resource>
</parameter>
</Parameters>
</resource>
</parameter>
<parameter>
<name value="outcome" />
<resource>
<OperationOutcome>
<issue>
<severity value="information" />
<details>
<text value="Encounter merge completed successfully" />
</details>
</issue>
</OperationOutcome>
</resource>
</parameter>
<parameter>
<name value="result" />
<resource>
<Encounter xmlns="http://hl7.org/fhir">
<id value="enc02" />
<identifier>
<use value="official" />
<system value="http://www.hospital-a/localid" />
<value value="1000000002" />
<assigner>
<display value="Hospital A" />
</assigner>
</identifier>
<identifier>
<use value="old" />
<system value="http://www.hospital-a/localid" />
<value value="1000000001" />
<assigner>
<display value="Hospital A" />
</assigner>
</identifier>
<status value="completed"/>
<class>
<coding>
<system value="http://terminology.hl7.org/CodeSystem/v3-ActCode"/>
<code value="AMB"/>
<display value="ambulatory"/>
</coding>
</class>
<priority>
<coding>
<system value="http://snomed.info/sct"/>
<code value="17621005"/>
<display value="Normal"/>
</coding>
</priority>
<type>
<coding>
<system value="http://snomed.info/sct"/>
<code value="11429006"/>
<display value="Consultation"/>
</coding>
</type>
<subject>
<reference value="Patient/f201"/>
<display value="Roel"/>
</subject>
<serviceProvider>
<reference value="Organization/f201"/>
</serviceProvider>
<participant>
<actor>
<reference value="Practitioner/f201"/>
</actor>
</participant>
<reason>
<value>
<concept>
<text value="The patient had fever peaks over the last couple of days. He is worried about these
peaks."/>
</concept>
</value>
</reason>
</Encounter>
</resource>
</parameter>
</Parameters>
Response: Example Provenance for $merge
<Provenance xmlns="http://hl7.org/fhir">
<id value="add4712f870b484dada83e80a249d7fb" />
<meta>
<versionId value="2" />
<lastUpdated value="2019-09-15T17:39:26.3561523-04:00" />
</meta>
<text>
<status value="generated" />
<div xmlns="http://www.w3.org/1999/xhtml">
<span style="color: gray;">target:</span> Encounter/enc02/_history/41<br /><span style="color: gray;">target:</span> Encounter/enc01/_history/63<br /><span style="color: gray;">activity:</span> Merge Record Lifecycle Event<br /><hr /><span style="color: gray;">who:</span> Fixmeup, Steve Dr
</div>
</text>
<target>
<reference value="Encounter/enc02/_history/41" />
</target>
<target>
<reference value="Encounter/enc01/_history/63" />
</target>
<occurredPeriod>
<start value="2019-09-15T17:38:56.3087526-04:00" />
<end value="2019-09-15T17:39:26.3544498-04:00" />
</occurredPeriod>
<recorded value="2019-09-15T17:38:56.3087526-04:00" />
<activity>
<coding>
<system value="http://terminology.hl7.org/CodeSystem/iso-21089-lifecycle" />
<code value="merge" />
</coding>
<text value="Merge Record Lifecycle Event" />
</activity>
<agent>
<type>
<coding>
<system value="http://terminology.hl7.org/CodeSystem/provenance-participant-type" />
<code value="performer" />
</coding>
<text value="Performer" />
</type>
<who>
<identifier>
<value value="UID123234" />
</identifier>
<display value="Fixmeup, Steve Dr" />
</who>
</agent>
</Provenance>
For more information about operations, including how they are invoked, see Operations.
FHIR ®© HL7.org 2011+. FHIR R6 hl7.fhir.core#6.0.0-ballot3 generated on Sat, Aug 30, 2025 14:27+0000.
Links: Search |
Version History |
Contents |
Glossary |
QA |
Compare to R5 |
|
Propose a change