The FHIR R4 CarePlan resource represents a set of planned activities, interventions, and goals for a patient or group of patients. Care plans describe what care is intended, who is responsible, and when activities should occur, supporting coordinated and longitudinal care delivery.
Health Gorilla exposes CarePlan as part of its FHIR R4 API to support access to patient-centered care planning information.
Use Cases
- Retrieving a patient’s active or historical care plans
- Reviewing planned interventions and goals across care teams
- Supporting care coordination, case management, and longitudinal care workflows
- Displaying structured care plans within patient charts or care-management tools
- Filtering care plans by intent, status, or clinical category
Scope and Behavior
This documentation describes the FHIR R4 API interface for CarePlan. 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 CarePlan 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, CarePlan is most commonly accessed as part of patient record retrieval workflows, where care planning data may be aggregated from connected clinical sources and normalized for longitudinal review. This resource supports care coordination, case management, and interdisciplinary collaboration by exposing structured goals, planned activities, and responsible participants alongside other patient clinical data.
Authentication
All requests to the FHIR R4 API require OAuth 2.0 authentication using a bearer token. Unauthorized requests return a 401 Unauthorized response.
Required Scopes
careplan.readfor GETcareplan.writefor POST, PUT, and DELETE
For details on authentication and token acquisition, see OAuth 2.0 Authentication.
Search Behavior
- Searches are scoped to the authenticated tenant.
- The
patientparameter 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 care plan status | draft, active, completed | token |
intent | Filters by care plan intent | plan, order, proposal | token |
category | Filters by care plan type | assess-plan, disease-management | token |
date | Filters by plan period | ge2023-01-01, le2024-12-31 | date |
author | Filters by plan author | Practitioner/{id} | Reference |
Commonly Returned Resource Attributes
The following attributes are commonly present in CarePlan resources returned by Health Gorilla.
| Attribute | Description | Example Values | FHIR Data Type |
|---|---|---|---|
subject | Patient or group the care plan applies to | Patient/{id} | Reference(Patient) |
status | Current state of the care plan | draft, active, completed | code |
intent | Purpose or level of authority | plan, order, proposal | code |
category | Type or clinical focus of the care plan | assess-plan | CodeableConcept[] |
title | Human-readable title | Free text | string |
description | Summary description of the care plan | Free text | string |
period | Time period the care plan covers | start, end dates | Period |
author | Individual or organization who created the care plan | Practitioner/{id} | Reference(Practitioner) |
careTeam | Participants involved in the plan | CareTeam/{id} | Reference[] |
goal | Goals addressed by the care plan | Goal/{id} | Reference[] |
activity | Planned actions or interventions | Structured activity entries | BackboneElement[] |
Notifications
The FHIR R4 API does not provide direct resource-change subscriptions for CarePlan. Changes to care planning information may surface through broader notification workflows, depending on enabled Health Gorilla products and configuration.
Error Handling
All CarePlan operations use standard Health Gorilla error handling and return a FHIR OperationOutcome resource for structured error details. For more information, go to Error Handling.