Conventions
The house rules for building against Palamond, on one page.
A short checklist of the conventions that keep an integration consistent with the platform. Each links to the concept behind it.
Import codes, never hardcode them
Every Palamond FHIR coordinate (code system, extension url, identifier system, meta.tag value) is exported from @palamond/sdk/codes, and the standard terminologies come with token helpers (loinc, snomed, rxnorm, icd10cm, and searchToken for any coding constant). Use those; do not paste literal strings. A typo in a magic string fails silently: a search just returns nothing.
import { loinc } from '@palamond/sdk/codes';
await palamond.searchResources('Observation', { code: loinc('8867-4') });See Codes and the Codes reference.
Leave tenancy to the server
Palamond is multi-tenant, and the API enforces the boundary for you. Every call is scoped to the signed-in patient's record inside their organization. Do not stamp organization references on anything, and do not derive a tenant from user input. Your one tenancy job is homing a self-registered patient once, via POST /v1/onboarding. See Organizations and Organization Scoping.
Let the server own permissions
Shape the UI around what the patient can do, but treat a 403 as a normal outcome, not an error to retry. The platform's access policies are the final word. See Roles and access.
Act through endpoints, read through FHIR
Observations, orders, encounters, and care plans are produced by the platform when you call a workflow endpoint. Your app submits the input (a QuestionnaireResponse, a reschedule, a decision) through the named endpoint and reads the result back from the record. It never hand-builds the finished resource; the record plane answers 405 if you try, naming the endpoint to use. See the API overview and Endpoints.
Complete tasks through their endpoint
A patient task is finished with POST /v1/tasks/{id}/complete, referencing a QuestionnaireResponse or carrying measurements inline. Never update a Task's status yourself. See Encounters and Tasks.
Expect errors as HTTP statuses
Business failures surface as proper HTTP statuses carrying the { error: { code, message, details } } envelope, never as a 200 with a failure inside. Branch on error.code, show error.message. See Errors and Limits.
Read by lineage, not by guesswork
To assemble a coherent view of a patient's journey, follow the EpisodeOfCare join key rather than stitching resources by time or name. See Episode lineage.
Reschedule is one call
There is no in-place move for an appointment. POST /v1/appointments/{id}/reschedule cancels the original and books a linked replacement in one step. See Appointments.
Write plainly, and never use em dashes
Documentation, UI copy, and labels stay in a clear, direct voice. Do not use em dashes anywhere in user-facing text. Use a comma, a colon, parentheses, or two sentences instead. This is a hard rule across the product.