The FHIR R4 Goal resource is used to capture a patient’s health goals, including both clinical and non-clinical objectives. It allows the tracking of a goal’s status, target date, achievement, and other relevant details, providing a structured way to monitor progress towards health improvement.
Health Gorilla exposes Goal as part of its FHIR R4 API to support patient-centric tracking of clinical and wellness objectives.
Use Cases
- Creating a new treatment goal for a patient
- Retrieving patient progress toward a specific health goal
- Updating a patient's health goal as their treatment plan evolves
Scope and Behavior
This documentation describes the FHIR R4 API interface for Goal. 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 Goal 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, Goal is most commonly accessed as part of patient record retrieval workflows, where care objectives may be aggregated and normalized for longitudinal review. This resource supports care planning, progress tracking, and outcome evaluation use cases.
Authentication
All requests to the FHIR R4 API require OAuth 2.0 authentication using a bearer token. Unauthorized requests return 401 Unauthorized responses.
Required Scopes
goal.readfor GETgoal.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: The parameters listed below are not exhaustive and reflect commonly used fields in typical Health Gorilla workflows. Supported parameters and behavior may vary by configuration.
Frequently Used Search Parameters
| Parameter | Description | Example Values | FHIR Data Type |
|---|---|---|---|
patient | Filters by patient | Patient/{id} | Reference |
status | Filters by goal lifecycle status | active, completed, cancelled | token |
category | Filters by goal category | clinical, behavioral | token |
priority | Filters by goal priority | high, medium, low | token |
start-date | Filters by goal start date | ge2024-01-01, le2024-12-31 | date |
target-date | Filters by goal target date | ge2024-01-01, le2024-12-31 | date |
Commonly Returned Resource Attributes
| Attribute | Description | Example Values | FHIR Data Type |
|---|---|---|---|
status | Current lifecycle status of the goal | active, completed | code |
category | Category of the goal | clinical | CodeableConcept[] |
priority | Priority of the goal | high | CodeableConcept |
description | Description of the goal | Improve cardiovascular health | CodeableConcept |
startDate | Date the goal began | 2024-01-01 | date |
target | Target criteria for achieving the goal | Structured target entries | BackboneElement[] |
achievementStatus | Measure of goal achievement | achieved, in-progress | CodeableConcept |
Notifications
The FHIR R4 API does not provide direct resource-change subscriptions for Goal. Changes to goal information may surface through broader notification workflows, depending on enabled Health Gorilla products and configuration.
Error Handling
All Goal operations follow standard Health Gorilla error handling, including use of FHIR OperationOutcome for structured responses. For more information, go to: Error Handling.