Declared capabilities of the Huli Public FHIR R5 API at https://api.huli.io/fhir/R5.

Create a DocumentReference together with its binary in one request. Two intake modes are accepted: (1) an inline DocumentReference whose binary rides in content[0].attachment.data (base64); (2) a multipart/form-data body with a file part plus subject (Patient reference or id) and optional encounter and category fields. Returns the created DocumentReference; a subsequent read carries a time-limited signed download URL.

Appointment profile for the Huli healthcare platform (FHIR R5). Covers scheduling workflows including multi-resource participants (practitioners, rooms, equipment), FHIR-aligned status lifecycle, SNOMED-coded appointment types, and recurring appointment series via the native R5 recurrenceTemplate element.

Key design decisions:

• start and end are extracted from the PostgreSQL TSTZRANGE time_slot column (lower/upper bounds).
• Status codes are already FHIR-aligned (stored in appointment_status_lkp with fhir_code column).
• Appointment types are SNOMED-coded from appointment_type_lkp.
• Patient confirmation status uses a custom extension since FHIR R5 has no standard element for this distinct workflow step. It is server-derived and read-only (emitted on read, ignored on write), as are appointmentType and specialty (both derived from the chosen service).
• serviceType is required on write (1..1): its single coding, under the Huli org-service CodeSystem, names the org service the appointment booking derives appointment type, specialty, booking policy, and resource requirements from. A missing or unresolvable serviceType is rejected 422. In R5 serviceType is CodeableReference; the org-service coding rides serviceType.concept.
• priority is a CodeableConcept in R5 (R4 used an unsignedInt). The stored numeric priority (0 = routine) rides a coding under the Huli appointment-priority CodeSystem (code = the number) and is echoed in .text, so a coded read round-trips to the exact value a write accepts.
• Staff-only operational notes are NOT exposed through this profile, on read or write (D-008) — same as R4. Neither Appointment.comment nor Appointment.note carries it; the codec has no Note field at all today, and Comment is populated only on the cancel path (an inbound comment resolves to the cancellation note, mirroring R4).
• The partitioned table's composite PK (id_appointment + time_slot_start) is an implementation detail; the FHIR resource uses id_appointment alone.

Recurring series (R5):

• A recurring booking is represented by a master Appointment carrying a recurrenceTemplate (timezone + recurrence rule + first occurrence date).
• Generated occurrences reference the master through recurrenceId (the 1-based occurrence ordinal).
• subject (the new R5 Appointment.subject element) records the patient the series is booked for, independent of the per-occurrence participant.actor list. (FHIR R5 has no originalSubject element — the series subject rides the standard Appointment.subject.)

Series edit scope — _recurrenceScope query parameter (on PUT): Mutations against an occurrence in a series select their scope with the _recurrenceScope query parameter:

• this — the single targeted occurrence only (the default).
• this-and-following — the targeted occurrence and every later one.
• all — the entire series (every occurrence + the master template).

A PUT /fhir/R5/Appointment/{id}?_recurrenceScope=<scope> with status = cancelled cancels the occurrences the scope selects; a PUT with any other status applies the edit to the same set. There is no REST delete on this API. Omitting _recurrenceScope is equivalent to this.

The all scope is metadata-only (description, patientInstruction, serviceType, specialty, status, priority). A full-representation PUT always carries start/end, so the server compares them (and the participant set) against the targeted occurrence: when they match, the metadata diff is applied across the series; when they differ (a real reschedule/participant change) the request is rejected with 400 (HPB-00101). Reschedule or re-staff via this / this-and-following.

Clinical-note projection of a Huli encounter (FHIR R5). section[] carries the encounter's clinical narrative as LOINC-coded narrative blocks:

• 10154-3 Chief complaint
• 10164-2 History of present illness
• 29545-1 Physical findings
• 51848-0 Assessment
• 18776-5 Plan of care
• 29308-4 Diagnosis (read-only projection)

status maps from the encounter status (preliminary / final / entered-in-error). Writes route through the practice encounter service, so a Composition create/update inherits the encounter guard stack.

Write restrictions:

• encounter is server-assigned. A create (POST) allocates a new encounter row, so a client-supplied encounter is rejected (400) rather than silently ignored.
• A finalized note cannot be voided. Setting status to entered-in-error on a note that is already final is rejected (409): the underlying encounter is finalized and the encounter state machine forbids finalized → cancelled. Void a preliminary note instead.

Minimal Condition profile (FHIR R5) for encounter-level diagnoses. Used as the target of Encounter.diagnosis.condition CodeableReferences, typically as contained resources within HuliEncounter.

Diagnoses in Huli are ICD-10 coded (assessment_plan.diagnoses[]) with system URI http://hl7.org/fhir/sid/icd-10 already present in source data. The type field ("primary"/"secondary") is conveyed through Encounter.diagnosis.use on the parent Encounter (R5 dropped the numeric diagnosis.rank used in R4).

Pointer to an uploaded patient document (FHIR R5). status is current for an active document and entered-in-error once soft-deleted. content[0].attachment carries the contentType, the 30-minute signed url (read), the byte size, the base64-encoded SHA-256 hash, and the title (filename). The document category is in category; the clinical encounter (when bound) is referenced directly from context (R5 flattened the R4 context backbone to a plain Reference list). Upload via the $upload operation (base64 inline or multipart) or POST with content[0].attachment.data.

Encounter profile for the Huli healthcare platform (FHIR R5). Represents ambulatory, emergency, inpatient, and virtual encounters with the SOAP-structured clinical workflow.

Key design decisions:

• Huli's encounter_status = "completed" maps to FHIR's status = "completed" (R5 renamed the R4 finished status code to completed, which now matches the Huli source value directly).
• class (a CodeableConcept list in R5) uses v3-ActCode: ambulatory→AMB, emergency→EMER, inpatient→IMP, virtual→VR.
• subject is tightened to 1..1 (Huli always requires a patient).
• participant requires at least one entry (the performing practitioner). Write behavior: only participant[0].actor is read on write, and it is treated as a Practitioner (a Huli user id). Additional participants and PractitionerRole references are not consumed on write.
• SOAP Subjective (S) and Objective (O) narratives map to a contained ClinicalImpression.summary on the Encounter (S then O, separated by a blank line) and are writable. Vital signs and laboratory results are exposed as discrete HuliObservation resources. The remaining SOAP narrative content (assessment, plan, custom forms, drawings, orders) is not modelled through FHIR in this IG.
• Encounter.diagnosis is populated from assessment_plan.diagnoses[] using contained HuliCondition resources, referenced through the R5 diagnosis.condition CodeableReference. Primary vs secondary is conveyed via diagnosis.use (R5 dropped the numeric diagnosis.rank).
• Encounter.reason carries the chief complaint from clinical_data.reason as reason.value.concept.text.

HealthcareService profile (FHIR R5) for the bookable services a Huli tenant offers. Read/search-only on the Public API — a booking integrator discovers the services it may reference on Appointment.serviceType.

Each HealthcareService maps to one organization_service_catalog entry; HealthcareService.id is the org-service UUID, republished as a type.coding under the HuliOrgServiceCS CodeSystem (https://fhir.huli.ai/r5/CodeSystem/org-service).

MedicationRequest profile for the Huli healthcare platform (FHIR R5). Represents a single prescribed medication line recorded against a patient, projected from the encounter Plan section.

Key design decisions:

• medication is a single CodeableReference (R5 collapsed the R4 medication[x] choice). The drug is carried inline under medication.concept; medicationReference to a contained or external Medication is not supported.
• intent is always emitted as order; any client-supplied intent is normalized to order on write.
• A newly created medication auto-groups into a draft prescription whose id is returned on groupIdentifier.
• requester is server-stamped as the authenticated user on write — a client-supplied requester is not honored as the prescriber.
• The dosage is a single flat dosageInstruction[0] entry; multi-line dosing is not supported.

Observation profile (FHIR R5) covering vital signs, laboratory results, and clinical exam findings recorded against a Huli patient and (optionally) encounter.

Key design decisions:

• code is LOINC-coded; valueQuantity.code uses UCUM units.
• category is one of vital-signs, laboratory, or exam. The runtime derives category from the LOINC code via observationCategoryForCode.
• subject (Patient reference) is mandatory.
• encounter (Encounter reference) is optional — observations may be recorded outside an encounter (e.g., home blood-pressure logs).
• effectiveDateTime is required when known; effectivePeriod is not used.
• performer carries the practitioner reference when the observation was entered manually; device carries the device reference when sourced from an automated device.
• The new R5 triggeredBy and bodyStructure elements are not surfaced by the runtime and are left unconstrained.

Organization profile (FHIR R5) for the clinics, practices, and health systems that use Huli. Read-only on the Public API; provisioning happens during tenant onboarding rather than through partner-facing FHIR writes.

Each Huli tenant maps to a single Organization resource. Organization.id is the tenant UUID and matches the managingOrganization reference emitted on Patient resources. A client may read only the Organization that corresponds to its own authenticated tenant.

R5 note: the top-level telecom/address elements present in R4 were removed in R5 and folded into the contact backbone (contact.telecom, contact.address). The Huli R5 Organization surfaces contact details through contact.

Patient profile for the Huli healthcare platform (FHIR R5). Encodes the Huli patient data model including multi-surname naming conventions (LATAM, Iberian, Filipino, etc.), national identifiers (CURP, RFC, NSS, INE for MX; CED, DIMEX for CR; DPI for GT; PPN passports; MR medical record numbers), and demographics required by Mexican NOM-024.

Key design decisions:

• HumanName.family carries the primary surname (first_lastname); the second surname (second_lastname) goes in the second-lastname extension to preserve the boundary between the two.
• gender is mapped from demographics.biological_sex (M→male, F→female, I→other, null→unknown).
• active is derived from the status column (1=true, 3/4=false; status=5 records are not exposed).
• Birth place uses the standard extension patient-birthPlace.
• Blood type, when present, is emitted via the huli-blood-type extension.
• Private insurance entries are emitted as a repeating huli-private-insurance extension (one per insurance row).

Identifier system URIs:

• CURP → http://www.renapo.gob.mx/curp
• RFC → http://www.sat.gob.mx/rfc
• NSS → http://www.imss.gob.mx/nss
• INE → http://www.ine.mx/credencial
• CED → http://www.tse.go.cr/cedula
• DIMEX → http://www.migracion.go.cr/dimex
• DPI → http://www.renap.gob.gt/dpi
• PPN → http://hl7.org/fhir/sid/passport-<ISO-3166-alpha-2> (per country)
• MR → empty system (org-local)

Practitioner profile (FHIR R5) for clinicians registered in Huli. Read-only on the Public API; provisioning happens through the operator-facing Huli platform rather than through partner-facing FHIR writes.

The Public API emits the practitioner's display name (given + primary surname, plus an optional second surname carried on the second-lastname extension matching HuliPatient) and the active flag. The profile permits additional elements (identifier, telecom, gender, qualification) for partner systems that import data from sources beyond the Public API.

PractitionerRole profile (FHIR R5) for the schedulable practitioner resources a Huli tenant exposes. Read/search-only on the Public API — a booking integrator resolves the practitioner and the location(s) that back a schedule.

PractitionerRole.practitioner references the HuliPractitioner; the location reference(s) point at the room(s) the role works from.

Schedule profile (FHIR R5) for the availability an actor (HuliPractitionerRole and/or room) offers. Read/search-only on the Public API — a booking integrator discovers, via service-type, which practitioner/room combinations deliver an org service.

R5 note: Schedule.serviceType is a CodeableReference in R5 (a bare CodeableConcept in R4); Huli republishes the booked org-service UUID under serviceType.concept.coding using the HuliOrgServiceCS CodeSystem (https://fhir.huli.ai/r5/CodeSystem/org-service).

ServiceRequest profile for the Huli healthcare platform (FHIR R5). Represents a single study or lab order placed against a patient, projected from the encounter Plan section.

Key design decisions:

• code is a single CodeableReference (R5 changed the R4 CodeableConcept). The ordered service is carried inline under code.concept; the display is required on write.
• intent is always emitted as order; any client-supplied intent is normalized to order on write.
• On write the create path always stamps status = active; a client-supplied status is accepted and ignored. On read the Huli "cancelled" request maps to FHIR revoked (R5 ServiceRequest.status has no cancelled).
• category is one of laboratory / clinical / procedure / referral.
• orderDetail[] (extra items of a multi-item order) is read-only — it is not consumed on write. Each extra item is emitted as the R5 orderDetail BackboneElement: the item concept rides parameterFocus.concept, mirrored in the mandatory parameter (R5 makes parameter 1..*) as parameter.valueCodeableConcept, with parameter.code naming it a Huli service-order item. This conforms to the R5 base orderDetail type.

Slot profile (FHIR R5) for the computed availability windows on a HuliSchedule. Search-only on the Public API — a booking integrator searches by schedule or actor over a start/end window to find a free window, then creates an Appointment for it. Slots are computed, not persisted, so there is no read-by-id interaction.

Patient blood type, sourced from profile_data.demographics.blood_type. Emitted by the runtime as valueCode (e.g., O+, A-, AB+). The value is the raw string stored by Huli; no value set is currently bound because partner clinics in LATAM use heterogeneous conventions.

Mapping: profile_data.demographics.blood_type JSONB scalar.

Audit detail about an appointment cancellation. The structured FHIR Appointment.cancelationReason carries the SNOMED-coded reason; this extension carries the operational metadata (actor, timestamp, free-text notes) that Huli additionally records.

Sub-extensions:

• cancelledBy (Reference, required when extension is present — a logical reference: valueReference.identifier carries the internal Huli user id of the cancelling actor under system = https://huli.io/fhir/identifier/user-id, with no literal reference and no type. The actor can be any staff identity — practitioner, receptionist, accountant, a service account, or the Huli "Sistema" sentinel — and is not exposed as a resource on this API; see D-013. Earlier releases emitted a typed Reference(Practitioner) literal, which mislabeled non-practitioner actors.)
• cancelledOn (dateTime, optional)
• cancellationNotes (string, optional)

Mapping: appointment.cancelled_by / .cancelled_on / .cancellation_notes columns.

Patient confirmation status for an appointment, representing whether the patient has confirmed, declined, or not yet responded to the appointment. This is distinct from Appointment.participant.status which tracks the provider's acceptance.

Runtime values (emitted by appointment_codec.go confirmationStatusCode):

• unconfirmed (Sin confirmar) — patient has not responded
• confirmed (Confirmada) — patient confirmed attendance
• cancelled (Cancelada) — cancelled before confirmation

Mapping: appointment.id_confirmation_status → one of the runtime codes above. Server-derived; read-only on write.

Audit attribution: the internal Huli user who created the appointment. Distinct from Appointment.participant, which records clinical participants rather than the actor who booked the slot.

The actor can be ANY staff identity — practitioner, receptionist, accountant, a service account, or the Huli "Sistema" sentinel — and is not exposed as a resource on this API. The value is therefore a logical reference: valueReference.identifier carries the Huli user id under system = https://huli.io/fhir/identifier/user-id, with no literal reference and no type (D-013). Earlier releases emitted a typed Reference(Practitioner) literal; that mislabeled non-practitioner actors and minted unresolvable references, and was retired.

Mapping: the id of the user who created the appointment, projected as valueReference.identifier (logical reference).

Ethnicity classification for Latin American healthcare contexts, aligned with Mexican NOM-024-SSA3 requirements for tracking indigenous and Afro-descendant populations.

Status — experimental and IG-only. This extension defines a forward-compatible contract for ethnicity data. The Public API does not emit it on Patient resources at this revision, and partner systems should not require its presence.

Mapping shape: sourced from the patient demographics' ethnicity sub-object. A group value maps to a display string, while the is_indigenous and is_afromexican flags map to specific codes in the bound value set.

Point-in-time insurance snapshot captured at the moment an appointment was booked. Independent of the patient's current insurance list — the snapshot is immutable history attached to the appointment.

Sub-extensions:

• provider (string, required) — insurer name at booking time
• policyNumber (string, optional) — policy number at booking time
• certificateNumber (string, optional) — certificate / member ID at booking time

Mapping: appointment.appointment_data.insurance JSONB sub-object.

Audit attribution: the internal Huli user who last modified the appointment. Companion to huli-created-by for audit attribution. The actor can be ANY staff identity — practitioner, receptionist, accountant, a service account, or the Huli "Sistema" sentinel — and is not exposed as a resource on this API. The value is therefore a logical reference: valueReference.identifier carries the Huli user id under system = https://huli.io/fhir/identifier/user-id, with no literal reference and no type (D-013). Earlier releases emitted a typed Reference(Practitioner) literal; that mislabeled non-practitioner actors and minted unresolvable references, and was retired.

Mapping: the id of the user who last modified the appointment, projected as valueReference.identifier (logical reference).

Private insurance entry attached to a patient. The runtime emits one huli-private-insurance extension per entry in profile_data.private_insurance[]. The extension is a complex extension with three sub-extensions; only provider is required.

Sub-extensions:

• provider (string, required) — insurer name
• policyNumber (string, optional) — patient policy number
• certificateNumber (string, optional) — certificate / member ID

The patient's second family name, following multi-surname naming conventions (LATAM, Iberian, Filipino, etc.). Placed on HumanName to preserve the boundary between the primary surname (HumanName.family) and the secondary one.

In Mexico, this maps to the apellido materno required by CURP and official documents; in Chile, to the segundo apellido. The extension is neutral about lineage — different cultures fill it from either parent.

Mapping: patient.second_lastname column (was mother_family prior to migration 00082).

SNOMED CT-coded appointment types used in the Huli scheduling system. Values sourced from appointment_type_lkp lookup table.

Reasons for appointment cancellation. Includes SNOMED-coded reasons where available and Huli-defined codes for operational reasons.

Patient confirmation statuses for appointment workflows.

Ethnicity categories for Latin American healthcare contexts.

Numeric priority of an appointment (0 = routine). R5 models Appointment.priority as a CodeableConcept; the Huli surface carries the raw numeric priority as the coding code under this system (and echoes it in .text) so a read round-trips to the exact value a write accepts.

Appointment cancellation reasons that do not have standard SNOMED CT codes. Used as a supplement to SNOMED-coded reasons.

Patient confirmation status for appointments. Represents whether the patient has responded to the appointment notification or whether the appointment was cancelled before confirmation. The Public API emits one of unconfirmed, confirmed, or cancelled.

Ethnicity categories for Latin American healthcare contexts, aligned with Mexican NOM-024-SSA3 requirements for demographic tracking.

Identity of an entry in a tenant's organization service catalog. The code is the org-service UUID. A booking client copies it verbatim onto Appointment.serviceType.concept (FHIR R5).

Synthetic booked single appointment with practitioner and patient participants (FHIR R5).

Synthetic recurring weekly appointment series using the R5 recurrenceTemplate element.

Synthetic ambulatory encounter with a diagnosis (FHIR R5).

Synthetic patient demonstrating LatAm naming, CURP, and demographics (FHIR R5).