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

Recent per-attempt delivery trail for a subscription, newest first. Sanitized — never exposes payloads, endpoints, or secrets. Read-only; requires system/Subscription.rs.

Re-enqueue past events whose occurred_at falls in a [from,to] window, for outage recovery / backfill. Only an active subscription may replay; the window is clamped to the retention horizon and one call re-enqueues at most 500 events. Requires system/Subscription.crud.

Aggregate delivery metrics for a subscription. Read-only; requires system/Subscription.rs.

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, category, and reviewer fields. The uploaded document is routed to a practitioner for review: name them with author[0] (inline) or the reviewer form field (multipart) — a Practitioner reference in the caller's organization — defaulting to the organization owner when omitted. Returns the created DocumentReference; a subsequent read carries a time-limited signed download URL.

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

Key design decisions:

• start and end are extracted from the appointment time slot (lower/upper bounds).
• Status codes are already FHIR-aligned.
• Appointment types are SNOMED-coded.
• Patient confirmation status uses a custom extension since FHIR R4 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.
• Staff-only operational notes are NOT exposed through this profile, on read or write (D-008). Appointment.comment is not a general read/write field — it is populated only on the cancel path (an inbound comment on a cancellation resolves to the cancellation note).
• The internal composite storage key is an implementation detail; the FHIR resource uses the appointment id alone.

Clinical-note projection of a Huli encounter. 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.

Minimal Condition profile for encounter-level diagnoses. Used as the target of Encounter.diagnosis.condition references, typically as contained resources within HuliEncounter.

Diagnoses in Huli are ICD-10 coded with system URI http://hl7.org/fhir/sid/icd-10 already present in source data. The type field ("primary"/"secondary") maps to diagnosis.rank on the parent Encounter.

Pointer to an uploaded patient document. 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 in context.encounter. Upload via the $upload operation (base64 inline or multipart) or POST with content[0].attachment.data.

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

Key design decisions:

• A completed encounter maps to FHIR status = "finished".
• Encounter.class 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].individual 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 the encounter's recorded diagnoses using contained HuliCondition resources.
• Encounter.reasonCode carries the chief complaint from the chief complaint as text.

Observation profile 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.

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

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

Patient profile for the Huli healthcare platform. 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; the second surname goes in the second-lastname extension to preserve the boundary between the two.
• gender is mapped from the patient's biological sex (M→male, F→female, I→other, null→unknown).
• active is derived from the patient's status (active→true, inactive→false; deleted records are not exposed).
• Birth place uses the standard R4 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 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.

The patient's blood type. Emitted by the runtime as valueCode (e.g., O+, A-, AB+). The value is the raw string recorded for the patient; no value set is currently bound because partner clinics in LATAM use heterogeneous conventions.

Mapping: the patient's recorded blood type.

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)

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 the runtime):

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

Mapping: server-derived; emits one of the runtime codes above. 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 indigenous and Afro-Mexican indicators 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: the insurance details captured on the appointment at booking time.

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 private insurance entry on the patient. 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.

SNOMED CT-coded appointment types used in the Huli scheduling system.

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.

Provenance of an address value emitted by the Huli Public API.

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 an organization's service catalog. The code is the org-service UUID. Emitted on HealthcareService.type.coding so a booking client can copy it verbatim onto Appointment.serviceType.

Synthetic booked appointment with practitioner and patient participants.

Synthetic ambulatory encounter with a diagnosis.

Synthetic patient demonstrating LatAm naming, CURP, and demographics.