The FHIR R4 Encounter resource is used to capture details about an interaction between a patient and a healthcare provider. It represents the entire span of care provided, including hospital visits, outpatient consultations, or any other health-related interaction. This resource records information such as the encounter type, status, participants, and diagnoses.
Health Gorilla exposes Encounter as part of its FHIR R4 API to support patient-centric access to visit and care episode information.
Use Cases
- Tracking patient admissions and discharges
- Logging patient encounters during hospital or outpatient visits
- Retrieving encounter details for billing and reimbursement
- Linking diagnostic reports or procedures to encounters
Scope and Behavior
This documentation describes the FHIR R4 API interface for Encounter. Health Gorilla’s platform may use additional internal services and data standards to acquire, normalize, and route clinical information. Only the FHIR R4–exposed behavior is documented here.
Health Gorilla supports a subset of the HL7 FHIR R4 Encounter resource. Not all optional elements defined in the HL7 specification may be stored, indexed, or returned. Unsupported or unrecognized elements may be ignored or normalized during processing.
In Health Gorilla, Encounter is most commonly accessed as part of patient record retrieval workflows, where visit and care episode data may be aggregated from connected clinical systems and normalized for longitudinal review. This resource supports care coordination, billing workflows, and linkage of related clinical resources.
Authentication
All requests require OAuth 2.0 authentication using a Bearer Token. Unauthorized requests return 401 Unauthorized responses.
Required scopes:
encounter.readfor GETencounter.writefor POST, PUT, DELETE
For more information, go to: OAuth 2.0 Authentication.
Search Behavior
Searches are scoped to the authenticated tenant. The patient parameter is required for patient-scoped searches and is recommended for most search use cases.
Results are returned as a FHIR Bundle. Pagination may be applied. Use standard FHIR pagination links (Bundle.link) to retrieve additional result pages.
Note: Supported parameters and behavior may vary by configuration.
Search Parameters
Encounter supports three search forms, and a request must use one of them:
identifieron its own.patient, optionally narrowed by the filters below._lastUpdated, optionally narrowed by the filters below.
| Parameter | Required | Description |
|---|---|---|
identifier | Required in the identifier search | Returns the encounter carrying the given identifier. |
patient | Required in the patient search | The patient whose encounters you want, as Patient/{id}. You can also search by a patient identifier using patient.identifier. |
_lastUpdated | Required in the cross-patient search | Filters on when the record was last written in the Health Gorilla FHIR server. Accepts a comparison prefix, for example ge2025-01-01. |
date | No | Filters on Encounter.period.start, so an encounter is matched on when it began rather than on the whole span it covers. |
type | No | Only the telephonic encounter value is accepted. Any other value returns HTTP 400 with "Filtering by type is not supported." |
processing-status | No | Filters on the processing status of the encounter. |
_offset | No | Skips the given number of results. |
_count | No | Limits the number of results returned per page. |
_tag | No | Filters on meta.tag. |
_security | No | Filters on meta.security. |
The identifier search accepts _revinclude for Condition:encounter, Procedure:encounter, DiagnosticReport:encounter, MedicationStatement:encounter, and Observation:encounter. The patient and _lastUpdated searches accept _revinclude=Provenance:target.
Resource Attributes
| Attribute | Description | Example Values | FHIR Data Type |
|---|---|---|---|
status | Current status of the encounter | in-progress, finished | code |
class | Classification of the encounter (e.g., inpatient, outpatient) | outpatient, emergency, inpatient | Coding |
type | Type of the encounter | office, outpatient | CodeableConcept[] |
period | Duration of the encounter | 2024-02-12T12:34:56Z/2024-02-12T15:34:56Z | Period |
serviceProvider | Organization responsible for the encounter | Organization/{id} | Reference(Organization) |
diagnosis | Diagnoses associated with the encounter | Condition/{id} | BackboneElement[] |
participant | Participants involved in the encounter | Practitioner/{id}, RelatedPerson/{id} | BackboneElement[] |
Notifications
The FHIR R4 API does not provide direct resource-change subscriptions for Encounter. Changes to encounter information may surface through broader notification workflows, depending on enabled Health Gorilla products and configuration.
Error Handling
All Encounter operations follow standard Health Gorilla error handling, including use of FHIR OperationOutcome for structured responses. For more information, go to: Error Handling.