Enroll in a Care Plan

A care plan is a FHIR CarePlan that instantiates a governed protocol. Two states matter to your app: draft (proposed, not yet acting) and active (its tasks and visits are issued and the patient is being cared for). You never build the plan graph by hand; the enrollment endpoints own the lifecycle.

There are two entry points:

Patient-initiated: your app enrolls the patient into a public offering, then activates it in the same flow.
Provider-proposed: a clinician has already left a draft CarePlan. Your app shows it as "Proposed" and the patient accepts (activate) or declines (unenroll).

Find the offering

protocols.list reads the catalog; entries with a protocol canonical are enrollable.

const catalog = await palamond.protocols.list();
const enrollable = catalog.filter((p) => p.protocol);

Enroll (creates the draft)

const { carePlan, plannedActionCount } = await palamond.enrollments.create({
  healthcareService: enrollable[0].healthcareService,
});
// carePlan.status === 'draft'

Enrolling is idempotent: re-enrolling in the same offering reuses the draft. A plan that allows only a single enrollment answers 409 conflict when one already ran.

Activate (starts the plan)

const activated = await palamond.enrollments.activate(carePlan.id);
// activated.carePlan.status === 'active'
// activated.createdTaskCount, activated.createdAppointmentCount

Activation schedules the plan's visits and issues its first patient tasks. From here the patient works the plan the usual way: read tasks from the record, complete them through tasks.

Accepting a provider-proposed plan

The draft already exists, so you skip the enroll step. Detect proposals on the record plane and activate on acceptance:

const proposed = await palamond.searchResources('CarePlan', { status: 'draft' });

await palamond.enrollments.activate(proposed[0].id);

Unenrolling

Ending a plan revokes the CarePlan and cancels its open tasks. It is always recorded as the patient's own request.

await palamond.enrollments.end(carePlan.id);

An optional second argument { reason: '...' } records why, when the patient gives one.

What the platform does for you

Pins the protocol version the plan instantiates, so a protocol published later never mutates an in-flight plan.
Schedules each recurring action and creates the patient-facing tasks with the right visibility.
Routes clinician work to the correct care-team queue and links visits back to the plan.

You read state back from the record (CarePlan and its Tasks), never from bookkeeping.