The FHIR R4 CarePlan resource outlines a patient's overall care plan, including goals, interventions, and the expected outcomes. It helps coordinate care between healthcare providers and ensures that patient care is managed and delivered in a structured manner.
Use Cases
- Retrieve a patient's care plan to track ongoing treatments and interventions
- Update a care plan to reflect changes in the patient's goals or care strategies
- Remove outdated or incorrect care plans
- Filter care plans by intent, status, or clinical category
Base URLs
- Production:
https://api.healthgorilla.com/fhir/R4/CarePlan - Sandbox:
https://sandbox.api.healthgorilla.com/fhir/R4/CarePlan
Authentication
All requests require OAuth 2.0 authentication using a Bearer Token. Unauthorized requests return 401 Unauthorized responses.
Required Scopes
careplan.read– Required for reading CarePlan resources via GETcareplan.write– Required for creating, updating, or deleting CarePlans via POST, PUT, or DELETE
For more information, see OAuth 2.0 Authentication.
Supported Methods
| Method | Operation | Description |
|---|---|---|
GET | Read CarePlan | Retrieves a specific CarePlan record by its FHIR ID. |
GET | Search CarePlan | Searches for CarePlan records for a specified patient. |
POST | Create CarePlan | Submits a new CarePlan record to the Health Gorilla FHIR server. |
PUT | Update CarePlan | Updates an existing CarePlan record by full resource replacement. |
DELETE | Delete CarePlan | Removes an existing CarePlan record from the system by full resource deletion. |
Frequently Used Search Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
patient | string | Yes | Filters by patient ID (Patient/{id}) |
status | string | No | Filters by care plan status (CarePlanStatus) |
category | string | No | Filters by clinical category (CarePlanCategory) (example only) |
intent | string | No | Filters by intent (CarePlanIntent) |
Commonly Returned Resource Attributes
| Attribute | Description | Example Values | FHIR Data Type | Required | |
|---|---|---|---|---|---|
id | Logical ID of the CarePlan | careplan-12345 | id | Yes | |
status | Current lifecycle status of the plan | active | code | Yes | |
intent | Purpose behind the creation of the plan | plan, proposal, order | code | Yes | |
subject | Reference to the patient (or group) this care plan is for | Patient/12345 | `Reference(Patient | Group)` | Yes |
category | High-level classification of the plan | chronic care (example) | CodeableConcept[] | No | |
title | Human-readable title for the plan | "Asthma Management Plan" | string | No | |
description | Narrative description of the care plan | "Patient will use inhaler twice daily..." | string | No | |
period | Time period the plan covers | start: 2023-01-01, end: 2023-12-31 | Period | No | |
author | Who created or is responsible for the plan | Practitioner/789 | Reference(Practitioner) | No | |
careTeam | Individuals and organizations involved in executing the plan | CareTeam/123 | Reference(CareTeam[]) | No | |
goal | Goals the plan is intended to achieve | Goal/456 | Reference(Goal[]) | No | |
activity.detail.status | Status of a specific activity within the plan | in-progress | code | No | |
activity.detail.code | Description of planned activity | Take medication, Refer to specialist | CodeableConcept | No | |
activity.detail.description | Free-text description of the activity | "Patient will begin physical therapy twice weekly" | string | No |
Webhooks
Clients may subscribe to webhook notifications to monitor CarePlan activity, such as when new plans are added or updated by external systems. For more information, go to Webhooks & Polling.
Error Handling
All CarePlan operations follow standard Health Gorilla error handling conventions using the FHIR OperationOutcome resource. For more information, go to Error Handling.