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.
Use Cases
- Create a new treatment goal for a patient
- Retrieve patient progress towards a specific health goal
- Update a patient's health goal as their treatment plan evolves
Base URLs
- Production: https://api.healthgorilla.com/fhir/R4/Goal
- Sandbox: https://sandbox.healthgorilla.com/fhir/R4/Goal
Authentication
All requests 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.
Supported Methods
| Method | Operation | Description |
|---|---|---|
GET | Read Goal | Retrieves a specific Goal record by its FHIR ID. |
GET | Search Goal | Searches for Goal records for a specified patient. |
POST | Create Goal | Submits a new Goal record to the Health Gorilla FHIR server. |
PUT | Update Goal | Updates an existing Goal record by full resource replacement. |
DELETE | Delete Goal | Removes an existing Goal record from the system by full resource deletion. |
Frequently Used Search Parameters
| Parameter | Description | FHIR Value Set / Example Values | FHIR Data Type | Required |
|---|---|---|---|---|
patient | Filters by patient ID | Patient/{id} | Reference | Yes |
status | Filters by the current status of the goal | GoalStatus (active) | token | No |
category | Filters by the category of the goal | GoalCategory (clinical) | token | No |
priority | Filters by the priority of the goal | GoalPriority (high) | token | No |
startDate | Filters by the start date of the goal | ge2024-01-01, le2024-12-31 | date | No |
targetDate | Filters by the target date for achieving the goal | ge2024-01-01, le2024-12-31 | date | No |
Commonly Returned Resource Attributes
| Attribute | Description | Example Values | FHIR Data Type | Required |
|---|---|---|---|---|
status | The current status of the goal | active | CodeableConcept | Yes |
category | The category of the goal | clinical | CodeableConcept | No |
priority | The priority of the goal | high | CodeableConcept | No |
description | A description of the goal | Improve cardiovascular health | string | Yes |
targetDate | The date by which the goal is expected to be achieved | 2024-12-31 | date | No |
achievement | A measure of how well the goal has been met | achieved, in-progress | CodeableConcept | No |
Webhooks
Health Gorilla supports webhook-based notifications for changes to a patient's clinical data, including Goal resources. Clients can register a webhook endpoint to be notified when:
- A new goal is created for a patient.
- An existing goal is updated.
- A goal's status is changed or its target date is modified.
For more information, go to: Webhooks & Polling.
Error Handling
All Goal operations follow standard Health Gorilla error handling, including use of FHIR OperationOutcome for structured responses.
Common reasons for failure include missing required fields (e.g., patient, status), invalid codes, or insufficient authorization scope (goal.write). For more information, go to: Error Handling.