FHIR Encounter Resource Explained (R4): Status, Class, Locations and How EHRs Model a Visit

The FHIR Encounter resource is the record of a visit: "an interaction between a patient and healthcare provider(s) for the purpose of providing healthcare service(s) or assessing the health status of a patient," in the words of the FHIR R4 Encounter specification. Clinic visits, emergency department stays, inpatient admissions, home health visits and video visits are all Encounters, and most clinical resources produced during care point back to one.

If you build anything triggered by a visit (discharge follow-up, a census board, charge capture, an AI scribe filing a note), Encounter is the resource you will spend the most time on, and the first signal is usually an HL7 v2 ADT message, not FHIR. This guide covers both: R4 anatomy checked against version 4.0.1, the status lifecycle against ADT events, the PV1 mapping from the v2-to-FHIR implementation guide, US Core search, and where integrations break.

Key takeaways

• In base R4 only status (1..1, a modifier element) and class (1..1 Coding) are required. US Core also requires type (1..*) and subject (1..1).
• ADT events do not map one to one onto status. The v2-to-FHIR IG derives status from PV1-2 Patient Class and PV1-45 Discharge Date/Time: when a discharge time is present, status is finished.
• A transfer changes Encounter.location, not Encounter.status. Each location entry has its own status (planned, active, reserved, completed) and period.
• US Core servers SHALL support Encounter search by _id, patient, and date plus patient. Class, status, type, identifier and location searches are SHOULD, so read the CapabilityStatement first.
• Referenced Locations can be searched and returned with _include=Encounter:location. Contained Locations cannot. Default to references.
• R5 reshapes Encounter: class becomes 0..* CodeableConcept, finished becomes completed, period becomes actualPeriod and hospitalization becomes admission.

What is the FHIR Encounter resource?

An Encounter is one interaction between a patient and one or more providers, from pre-admission through discharge. It records the setting (class), the kind of visit (type), who took part, where the patient was, when it started and ended, and why it happened. Appointment books the visit. Encounter records what actually took place.

The spec draws that boundary explicitly: Appointment "is used for establishing a date for the encounter, while Encounter is applicable to information about the actual Encounter, i.e., the patient showing up." A planned Encounter is not the same object as the Appointment that scheduled it. For the booking side, see our FHIR scheduling API guide.

There is also no universal rule for what counts as one encounter. Some organizations create one per practitioner visit during a stay, others one for the whole stay, with child encounters grouped through Encounter.partOf. Find out which model each source uses before you map anything.

Encounter sits between the patient and the clinical data produced during the visit. The FHIR Patient resource is its subject, and Observations, Conditions, Procedures and DocumentReferences carry an encounter reference back to it. That reference is how you answer "what happened during this admission?" Our FHIR Observation guide shows the other end of that link.

FHIR Encounter anatomy: R4 elements and cardinality

R4 Encounter has more than twenty top-level elements, but only two are required: status and class. The table lists the elements integration engineers work with, with cardinality and binding from the 4.0.1 StructureDefinition and the requirement from the US Core Encounter profile (version 9.0.0) beside each.

R4 also has episodeOfCare, basedOn and account, all 0..*. Three US Core rules matter more than the table suggests. First, a server SHALL support at least one of reasonCode or reasonReference, and at least one of location or serviceProvider, and clients are expected to read both of each pair. Second, Encounter.diagnosis is not Must Support, so many servers carry encounter diagnoses on Condition instead. Third, US Core 9.0.0 adds the interpreter-needed extension as an additional USCDI requirement and marks meta.lastUpdated as Must Support. Our US Core implementation guide explains how Must Support plays out across resources.

What are the FHIR Encounter status values?

R4 Encounter.status uses a required value set of nine codes: planned, arrived, triaged, in-progress, onleave, finished, cancelled, entered-in-error and unknown. Status is a modifier element, so a client that ignores it can misread the whole record. A cancelled or entered-in-error encounter should never feed a census, an outreach list or a billing trigger.

The right-hand column is engineering convention, not normative mapping. The HL7 v2-to-FHIR IG does not assign a status per trigger event. Its PV1 segment to Encounter map sets status from PV1-2 when PV1-45 is empty, through a table 0004 to Encounter status map where P becomes planned, U becomes unknown and every other patient class becomes in-progress. When PV1-45 is valued, status is finished. Event names come from HL7 table 0003.

Four event types cause most of the bugs we see in encounter pipelines:

• A02 transfer does not change status. It closes the current location entry (status completed, period.end set) and opens a new one (status active).
• A08 update patient information can carry a changed PV1 on any day of the stay. Treat it as a replace of the visit fields you own, not as a lifecycle event.
• A13 cancel discharge moves a finished encounter back to in-progress and clears period.end. If your pipeline only handles forward motion, a cancelled discharge leaves a patient off the census and in your follow-up call queue.
• A11 cancel admit/visit has no single correct target. If the visit was called off, cancelled fits; if the admit was sent in error, entered-in-error fits. Pick one per source and document it.

R5 changes the list to planned, in-progress, on-hold, discharged, completed, cancelled, discontinued, entered-in-error and unknown, adds subjectStatus, and drops statusHistory and classHistory. The R5 Encounter page has the full list, and our R4 vs R5 vs R6 decision framework covers when the move is worth it.

Encounter.class vs Encounter.type vs serviceType

Class is the setting of care: 1..1 Coding in R4, bound extensibly to the v3 ActEncounterCode value set. Type is the specific kind of encounter and can repeat. ServiceType is the broad clinical service. Use class to route business rules, type for reporting and visit matching, and serviceType for department-level views.

The code system is http://terminology.hl7.org/CodeSystem/v3-ActCode, and the ActEncounterCode value set lists every code with its definition. VR is the code for telehealth video and phone visits. The binding is extensible, yet local codes and v2 table 0004 letters (I, O, E) still leak through from interface feeds, so normalize class on ingest and keep the original.

When the setting changes mid-visit, such as an emergency patient who is admitted, R4 allows either updating class and recording the old value in classHistory, or closing the emergency encounter and opening a new inpatient one. HL7 v2 signals the change with A06 (change an outpatient to an inpatient) and A07 (the reverse). A census that counts encounters instead of patients will double count the second pattern.

Type has only an example binding in the base spec. US Core makes it 1..* with an extensible binding. Synthea data on the public SMART sandbox uses SNOMED CT codes such as 185349003 "Encounter for check up (procedure)", while production systems often send local visit type codes with a text display.

Participants and locations: contained vs referenced

Participant lists who took part, each with a role in participant.type (for example ATND, attender) and an optional period. Location lists every place the patient was, each with its own status and period. A Location can be referenced as a standalone resource or contained inside the Encounter. References are the right default because only they can be searched and included.

Here is a real, trimmed response from the public HAPI FHIR R4 test server for Encounter?patient=Patient/137222314&_include=Encounter:location. The Location comes back as a second entry with search.mode set to include:

{
  "resourceType": "Bundle",
  "type": "searchset",
  "entry": [
    {
      "resource": {
        "resourceType": "Encounter",
        "id": "137222317",
        "status": "in-progress",
        "class": {
          "system": "http://terminology.hl7.org/CodeSystem/v3-ActCode",
          "code": "IMP",
          "display": "inpatient encounter"
        },
        "subject": { "reference": "Patient/137222314" },
        "period": { "start": "2026-07-23T08:00:00+02:00" },
        "location": [
          {
            "location": { "reference": "Location/137222316" },
            "status": "active"
          }
        ]
      },
      "search": { "mode": "match" }
    },
    {
      "resource": {
        "resourceType": "Location",
        "id": "137222316",
        "status": "active",
        "name": "Radiology Ward - Room 3",
        "mode": "instance",
        "physicalType": {
          "coding": [
            {
              "system": "http://terminology.hl7.org/CodeSystem/location-physical-type",
              "code": "ro",
              "display": "Room"
            }
          ]
        }
      },
      "search": { "mode": "include" }
    }
  ]
}

The contained form below is illustrative, written to show the syntax. The Location sits inside contained and the reference is a local fragment, #loc1:

{
  "resourceType": "Encounter",
  "id": "example-contained",
  "contained": [
    {
      "resourceType": "Location",
      "id": "loc1",
      "name": "3 West, Bed 12",
      "physicalType": {
        "coding": [
          {
            "system": "http://terminology.hl7.org/CodeSystem/location-physical-type",
            "code": "bd",
            "display": "Bed"
          }
        ]
      }
    }
  ],
  "status": "in-progress",
  "class": {
    "system": "http://terminology.hl7.org/CodeSystem/v3-ActCode",
    "code": "IMP"
  },
  "subject": { "reference": "Patient/example" },
  "location": [
    {
      "location": { "reference": "#loc1" },
      "status": "active",
      "period": { "start": "2026-07-23T08:00:00+02:00" }
    }
  ]
}

The R4 rules for contained resources explain the trade-off. A contained resource SHALL only be present if something in the container references it, SHALL NOT contain further contained resources, and SHALL NOT carry meta.versionId, meta.lastUpdated or meta.security. The spec says containment "SHOULD NOT be done when the content can be identified properly." A contained Location has no identity outside its Encounter, so you cannot search for it, include it, or recognize the same bed across two visits.

You will still meet contained Locations in data built from v2 feeds with free-text points of care. Resolve any # reference against contained before following a server URL, and never key bed logic on a local id. The bed, room and ward hierarchy lives on Location through Location.partOf, and Encounter.location.physicalType is a denormalized copy of the level so a consumer can pick the right entry without resolving every Location. Our real-time patient census guide shows how that location state drives a bed board.

Hospitalization details: admit source, discharge disposition, destination

The hospitalization component holds admission and discharge detail: where the patient came from (origin, admitSource), whether this is a readmission, diet and special arrangements, and where the patient went (destination, dischargeDisposition). R4 expects it to cover the same period as the encounter itself. US Core marks only dischargeDisposition as Must Support.

Discharge disposition drives post-acute and follow-up work: routine discharge home, transfer to a skilled nursing facility, hospice, and so on. The R4 base binding is only an example, and US Core points to its own discharge disposition value set with a preferred binding. This trimmed Synthea inpatient record from the public SMART R4 sandbox uses NUBC codes:

{
  "resourceType": "Encounter",
  "id": "c8067541-e4dd-4872-8415-528dfc80cd11",
  "status": "finished",
  "class": {
    "system": "http://terminology.hl7.org/CodeSystem/v3-ActCode",
    "code": "IMP"
  },
  "type": [
    {
      "coding": [
        {
          "system": "http://snomed.info/sct",
          "code": "183452005",
          "display": "Encounter Inpatient"
        }
      ]
    }
  ],
  "subject": { "reference": "Patient/1ac8947d-038f-4cc7-81fa-a32e694187e8" },
  "period": {
    "start": "1978-04-21T16:42:48+00:00",
    "end": "1978-04-22T17:43:48+00:00"
  },
  "reasonCode": [
    {
      "coding": [
        {
          "system": "http://snomed.info/sct",
          "code": "74400008",
          "display": "Appendicitis"
        }
      ]
    }
  ],
  "hospitalization": {
    "dischargeDisposition": {
      "coding": [
        {
          "system": "http://www.nubc.org/patient-discharge",
          "code": "01",
          "display": "Discharged to home care or self care (routine discharge)"
        }
      ]
    }
  },
  "serviceProvider": { "reference": "Organization/5d4b9df1-93ae-3bc9-b680-03249990e558" }
}

Three pitfalls here. Admit source in v2 (PV1-14, table 0023) has no suggested values, so the v2-to-FHIR IG provides no vocabulary map and you will need a site-specific one. Destination should point to a Location or Organization, and the IG says PV1-37 should become a new Location instance. And the outpatient records we sampled on both public servers carry no hospitalization element at all, so null handling is not optional.

How does HL7 PV1 map to a FHIR Encounter?

The HL7 Version 2 to FHIR implementation guide maps the PV1 and PV2 segments field by field onto Encounter. PV1-19 Visit Number becomes an identifier, PV1-2 Patient Class drives class and status, PV1-3 and PV1-6 become location entries, and PV1-44 and PV1-45 become the period. A valued PV1-45 sets status to finished.

The IG maps segments and message structures. It does not decide what an event means for your state machine, and PV1-2 values such as R (recurring patient) or B (obstetrics) map to in-progress, which is correct and tells a census nothing. Those decisions stay with you. For a worked channel that builds an R4 Bundle from ADT, see our v2 to FHIR Bundle mapping tables and the broader HL7v2 to FHIR migration guide.

Turning an ADT feed into FHIR Encounters? We run Mirth Connect interface engines in production and build EHR integration across Epic, Oracle Health (Cerner), athenahealth, eClinicalWorks and NextGen. Talk to our team and we will map your PV1 fields and event handling before you write the translator.

How do you search FHIR Encounters?

Search Encounters by patient and date for most workflows. US Core requires servers to support _id, patient, and date plus patient. Identifier, class, status, type, location, discharge disposition and _lastUpdated searches are SHOULD in the US Core server CapabilityStatement, so confirm each one on the server before you depend on it.

These requests run against the public HAPI R4 server. The last one uses a placeholder identifier system and value:

BASE=https://hapi.fhir.org/baseR4

# SHALL: a patient's encounters in a date window
curl -s "$BASE/Encounter?patient=Patient/137222314&date=ge2026-07-01&date=lt2026-08-01" \
  -H "Accept: application/fhir+json"

# SHOULD: inpatient only (token search on class)
curl -s -g "$BASE/Encounter?patient=Patient/137222314&class=http://terminology.hl7.org/CodeSystem/v3-ActCode|IMP" \
  -H "Accept: application/fhir+json"

# SHOULD: open encounters, with their Locations in the same Bundle
curl -s "$BASE/Encounter?patient=Patient/137222314&status=in-progress&_include=Encounter:location" \
  -H "Accept: application/fhir+json"

# Resolve an ADT visit number (PV1-19) to a FHIR Encounter (placeholder values)
curl -s -g "$BASE/Encounter?identifier=urn:oid:2.16.840.1.113883.19.5|V100045" \
  -H "Accept: application/fhir+json"

Date searches catch people. The date parameter searches Encounter.period, which is a range, so prefixes test overlap. Per the R4 search specification, "a missing upper boundary is 'greater than' any actual date," so an in-progress encounter with no end matches every ge query after its start. Use two date parameters to bound a window, and remember that _include=Encounter:location only returns referenced Locations. US Core also lists _revinclude=Provenance:target for Encounter. For more traps, see 10 FHIR search patterns developers get wrong.

How EHRs model encounters differently

US Core gives every conformant server the same Encounter profile, but the same visit can still look different from one system to the next. The differences cluster in five places: what counts as an encounter, how inpatient stays are split, how much location detail comes back, whether period is complete, and where diagnoses live.

• Outpatient vs inpatient. Ambulatory systems often create Encounters for contacts that are not visits, such as telephone calls, refill requests and documentation-only charts. Filter on class and type, not on the mere existence of an Encounter.
• Granularity. One Encounter per hospitalization, one per unit stay linked with partOf, or one per practitioner visit. The spec allows all three.
• Location detail. US Core lets a server meet the location requirement with serviceProvider alone, so some responses name the facility and say nothing about the unit, room or bed.
• Missing or partial periods. Period is Must Support, not required. Expect encounters with no end long after discharge, and timestamps without a time zone even though the R4 dateTime rule says one SHALL be present when hours and minutes are given. One Encounter we pulled from the public HAPI server has "start": "2026-07-28T12:31:57" with no offset.
• Diagnosis on Encounter vs Condition. Encounter.diagnosis is not Must Support in US Core, and the profile's reasonReference targets include the US Core Condition Encounter Diagnosis profile. Diagnoses therefore often arrive as Condition resources with an encounter reference. Query Condition by encounter too; our FHIR Condition guide covers both Condition profiles.

Epic documents its encounter identifier. Epic's interfaces guide says encounters are uniquely identified by the Contact Serial Number (CSN) and recommends matching on the CSN whenever your workflow has it. The Encounter.Search (Patient Chart) (R4) specification returns the CSN in Encounter.identifier and accepts identifier=<system>|<value>, where the system is the organization's OID for the CSN item; billing number and external visit ID systems are also accepted. Those OIDs vary by customer, so Epic's ID Types guide tells you to request them from each site. The same specification requires patient or subject, returns outpatient encounters only after check-in, leaves out upcoming appointments (use Appointment for those), and outside the Netherlands expects an Epic OID rather than ActCode as the class search system.

Behavior also varies by site within one vendor. Our guide to reading an EHR CapabilityStatement walks through that check, and why FHIR compliant does not mean interoperable covers the vendor extensions you will meet.

Visit-driven workflows: ADT trigger, then FHIR fetch

The pattern that holds up in production uses HL7 ADT as the trigger and FHIR as the source of truth. The ADT message tells you within seconds that something changed. A FHIR read then fetches the current Encounter, Locations and participants, and a scheduled reconcile query catches anything the feed missed or delivered out of order.

1. Receive ADT in an interface engine such as Mirth Connect, ACK promptly, and persist the raw message.
2. Deduplicate on MSH-10 message control ID, and key the visit on PV1-19 visit number.
3. Publish a small domain event (visit.admitted, visit.transferred, visit.discharged) rather than the parsed v2 message.
4. Resolve the Encounter by identifier, or by patient and date, with _include=Encounter:location.
5. Let consumers act on FHIR state, not on the event name, so a late A13 or an A11 simply produces a different state.
6. Run a scheduled patient and date reconcile search for active patients.

Where the EHR supports event-driven FHIR subscriptions, they can supplement the ADT trigger, and HL7 vs FHIR: when organizations need both covers running the two side by side. AI scribes follow the same pattern because the note must attach to the right Encounter id, as our ambient clinical documentation engineering guide explains.

Where teams get stuck with FHIR Encounter

Most Encounter bugs are not spec misreadings. They are state bugs: events processed in the wrong order, identifiers that do not line up, and reversals nobody handled. They tend to surface after go-live, when real patient flow exercises paths the sandbox never did, and each one costs a round of rework across the mapping, the data store and every downstream consumer.

• Keying on the wrong identifier. ADT gives you PV1-19; the FHIR API gives you a logical id. Store only one and you cannot join the two, and reconciliation becomes a manual project. Store both from day one, with the identifier system.
• Watching status alone. An A02 leaves status unchanged and moves only the location array. Census logic that watches status misses every transfer.
• Ignoring reversals. A11, A12 and A13 undo earlier events. Without them you call patients who were never discharged and queue charges for visits that did not happen.
• Trusting arrival order. A discharge can arrive before the transfer that preceded it. Order by the event time the message carries (EVN-6 when sent, otherwise EVN-2), not by arrival time.
• Assuming finished means billable. Finished says the visit ended. Coding and charges often finalize later, so a billing trigger needs its own readiness signal.
• Hard-coding R4 names. R5 renames period, hospitalization and several status codes. Keep element names inside one mapping layer.

FHIR Encounter implementation checklist

1. Read each server's CapabilityStatement and confirm which Encounter searches it supports.
2. Pull real encounters per class (AMB, EMER, IMP) and note which Must Support elements are actually populated.
3. Decide encounter granularity per source: per visit, per unit stay, or per hospitalization with partOf.
4. Store the FHIR logical id and every identifier (system plus value), including the ADT visit number.
5. Normalize class to ActEncounterCode on ingest and keep the original code.
6. Write the status state machine with A11, A12, A13, A21, A22 and A38, and document your A11 target.
7. Model transfers as location entries with status and period unless the source creates new encounters.
8. Read the visit reason from reasonCode or reasonReference, and the place from location or serviceProvider.
9. Query Condition by encounter for diagnoses instead of relying on Encounter.diagnosis.
10. Handle open periods and missing time zones explicitly.
11. Prefer referenced Locations and resolve contained ones locally.
12. Run a scheduled reconcile search to catch missed or reordered ADT messages.

Building visit-driven workflows on Epic, Oracle Health or athenahealth encounters? Our healthcare interoperability solutions team builds the ADT and FHIR integration layer, and our healthcare software product development team builds the event pipeline and services around it. Talk to our team to review your encounter model before it reaches production.