The FHIR R4 Observation resource represents measurements, test results, assessments, and other discrete clinical findings. This includes vital signs, lab results, social history, and imaging interpretations. Observations are central to longitudinal patient records and are often imported from multiple external sources in Health Gorilla's network.
Use Cases
- View a patient’s vitals, lab results, or imaging reports
- Monitor trends in blood pressure, glucose, or cholesterol
- Retrieve structured result values by LOINC code
- Link observations to encounters or diagnostic reports
Base URLs
- Production: https://api.healthgorilla.com/fhir/R4/Observation
- Sandbox: https://sandbox.healthgorilla.com/fhir/R4/Observation
Authentication
All requests require OAuth 2.0 authentication using a Bearer Token. Unauthorized requests return 401 Unauthorized responses.
Required Scopes
observation.readfor GETobservation.writefor POST, PUT, DELETE
For more information, go to: OAuth 2.0 Authentication.
Supported Methods
| Method | Operation | Description |
|---|---|---|
GET | Read Observation | Retrieves a specific Observation record by its FHIR ID. |
GET | Search Observation | Searches for Observation records for a specified patient. |
POST | Create Observation | Submits a new Observation record to the Health Gorilla FHIR server. |
PUT | Update Observation | Updates an existing Observation record by full resource replacement. |
DELETE | Delete Observation | Removes an existing Observation record from the system by full deletion. |
Search Parameters
Observation supports two search forms, and a request must satisfy one of them:
- Search by patient: provide
patient. - Search across patients: provide both
categoryand_lastUpdated.
| Parameter | Required | Description |
|---|---|---|
patient | Required in the patient search | The patient whose observations you want, as Patient/{id}. You can also search by a patient identifier using patient.identifier. |
category | Required in the cross-patient search | Filters on the observation category, for example laboratory or vital-signs. |
_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. |
code | No | Filters on the observation code. |
date | No | Filters on the clinical date the observation applies to, Observation.effective. |
encounter | No | Returns observations recorded during the given encounter, as Encounter/{id}. |
_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 search also accepts _include=Observation:subject and _include=Observation:related-target to return referenced resources, and _revinclude=Provenance:target to return the Provenance records describing where the results came from.
Resource Attributes
| Attribute | Description | Example Values | FHIR Data Type | Required |
|---|---|---|---|---|
id | Unique FHIR ID for the observation | obs-456789 | id | Yes |
status | Status of the observation | final | code | Yes |
category | Broad category of observation | vital-signs | CodeableConcept[] | No |
code | Specific observation code | 55284-4 — Blood pressure panel | CodeableConcept | Yes |
subject | The patient associated with the observation | Patient/{id} | Reference(Patient) | Yes |
effectiveDateTime | When the observation was made | 2024-03-01T08:00:00-07:00 | dateTime | Yes |
issued | Time when the observation was released | 2024-03-01T08:30:00-07:00 | instant | No |
valueQuantity | Measurement result (numerical) | 120 mmHg | Quantity | No |
valueCodeableConcept | Measurement result (coded text) | Negative, Reactive | CodeableConcept | No |
dataAbsentReason | Why a value is missing | not-performed, unknown | CodeableConcept | No |
referenceRange | Normal range associated with the result | 80–120 mmHg | Observation.ReferenceRange[] | No |
interpretation | Clinical interpretation of the result | high, normal, low | CodeableConcept[] | No |
performer | Who performed or reported the observation | Practitioner/{id}, Organization/{id} | Reference[] | No |
note | Comments or annotations | "Patient was fasting" | Annotation[] | No |
Webhooks
Clients can subscribe to webhook notifications when new observations are added to a patient’s chart (e.g., lab results, vitals). Webhooks may also trigger on updates to existing records depending on client configuration.
For more information, go to: Webhooks & Polling.
Error Handling
All Observation operations follow standard Health Gorilla error handling, including use of FHIR OperationOutcome for structured responses.
For more information, go to: Error Handling.