Encounters and Tasks

Two resources carry the operational work of a visit: the Encounter (the clinical contact) and the Task (a unit of work to do). Palamond models both with a distinctive rule: encounters are created lazily, and a task completion is the action that advances the workflow. Understanding those two ideas is most of what you need to build against them.

Encounters are created lazily

There is no pre-created planned encounter waiting for a visit. The Appointment is the scheduling source of truth; the Encounter is materialized only when the visit actually begins. When your app opens the visit experience, materialize it with one call:

const { encounter, created, reopened } = await palamond.appointments.startEncounter(appointmentId);

The call is idempotent and keyed by the appointment, so a double-click or a retry never produces two encounters: created tells you whether this call made it, and reopened whether a finished one was resumed. A 409 consent_required means required agreements are unmet; accept them via the agreements endpoints and retry (see Errors and Limits).

The materialized encounter copies the subject, modality, and care-plan links from the appointment and back-links to it via Encounter.appointment.

Find the encounter for an appointment by its back-link:

const encounters = await palamond.searchResources('Encounter', {
  appointment: `Appointment/${appointmentId}`,
});

Tasks: the patient's to-do list

A Task is one piece of work. The API exposes the patient's own tasks: complete a questionnaire, capture a measurement, decide an order. Clinician work (chart reviews, request reviews) is routed through care-team queues by the platform and is never visible to a patient session.

const tasks = await palamond.searchResources('Task', {
  status: 'requested,in-progress',
});

Read Task.status and Task.description to render the list, and let the SDK's getTaskKind tell you what each task is ('questionnaire' | 'measurements' | 'medication' | 'order'), so the right screen renders without inspecting the task's internals. getRequestedMeasurements and getMedicationOptions read the typed inputs the same way. Complete an Assessment walks through all four kinds.

Completing a task

tasks.complete is the one action. It takes the task (a bare id or a Task/<id> reference) and the work product, exactly one of questionnaireResponse, measurements, medicationRequest, or decline: true:

await palamond.tasks.complete(task.id, {
  questionnaireResponse: `QuestionnaireResponse/${response.id}`,
});

await palamond.tasks.complete(task.id, {
  measurements: [{ loinc: '29463-7', value: 72, unit: 'kg', code: 'kg' }],
});

A medication suggestion task completes with medicationRequest (the proposal recorded first via requests.create), or with decline: true when the patient wants none of the suggestions.

Every shape accepts an optional encounter to link the work to a visit. Completion is what moves the workflow: the platform stores the results, closes the task, and opens whatever comes next (for example the clinician review once an intake is done). It returns the completed Task.

One task kind has its own action: a task whose focus is an order proposal is completed by recording the decisions with orders.decide (see Orders).

Timing on restriction.period

Task.restriction.period carries two independent time semantics:

• period.start is a not-before gate. A task scheduled for the future is not yet actionable; completing it early answers 409 with details.notBefore. Hide or disable such tasks until their start.
• period.end is the deadline. A future deadline never blocks completion; it only marks the task overdue once it passes. Use it to sort and badge the to-do list.

A task that is already closed also answers 409 conflict, so a retried completion can never run twice. See Errors and Limits for the envelope.

What a patient app reads

A patient app works almost entirely from tasks, appointments, and encounters:

• upcoming and past visits from Appointment (and the Encounter once a visit has started),
• to-dos from Task (intake questionnaires, measurement capture, order decisions),
• the resource each task points at via Task.focus, to render the right screen.

Complete tasks through POST /v1/tasks/{id}/complete and the platform moves the workflow forward.