Huli FHIR Core Implementation Guide (R4) - Local Development build (v0.1.0) built by the FHIR (HL7® FHIR® Standard) Build Tools. See the Directory of published versions

Home

Official URL: https://fhir.huli.ai/r4/ImplementationGuide/huli.fhir.core.r4				Version: 0.1.0
Active as of 2026-09-11				Computable Name: HuliFHIRCoreR4

Huli FHIR Core Implementation Guide (R4)

FHIR R4 facade profiles for the Huli healthcare platform, targeting Latin American ambulatory care workflows. This IG package describes the R4 surface; a separate package will track the R5 surface when it ships.

URLs you will see in this IG

• Canonical URL — https://fhir.huli.ai/r4. The IG identifier used as the prefix for every profile, extension, and CodeSystem URL emitted by this IG and by the Huli Public API runtime. Per FHIR convention, the canonical URL does not need to resolve in a browser — it is an opaque identifier that establishes ownership and stability across versions.
• API base — https://api.huli.io/fhir/R4. The wire URL where resources are read and written. The published GET .../metadata CapabilityStatement and implementation.url published here use this base.
• Published site — https://developers.huli.ai/fhir/r4/. Where this IG is hosted for human consumption (the HTML site you are reading right now).

The canonical (.io) and the developer-portal host (.ai) are intentionally separate: the canonical is a stable wire identifier that must not change across re-hosting decisions, while the portal host is where Huli chooses to publish the rendered IG today.

Scope

This Implementation Guide covers the resources exposed by the Huli Public FHIR R4 API at https://api.huli.io/fhir/R4:

• Patient — read, search, create, update
• Appointment — read, search, create, update (optimistic concurrency via If-Match)
• Encounter — read, search, create, update (clinical Plan: diagnosis rank, diagnostic impression, follow-up plan)
• Observation — read, search, create, update
• MedicationRequest — read, search, create, update (clinical Plan; BAA-gated)
• ServiceRequest — read, search, create, update (clinical Plan; BAA-gated)
• Composition — read, search, create, update (clinical-note projection of an Encounter; optimistic concurrency via If-Match)
• DocumentReference — read, search, create, $upload (entered-in-error via update; BAA-gated)
• Patient/$everything — aggregate read of a patient's clinical record (Appointment, Encounter, Observation, Composition, DocumentReference, MedicationRequest, ServiceRequest), per-type scoped
• Practitioner — read, search
• Organization — read, search
• Discovery (read-only) — Location, PractitionerRole, HealthcareService, Schedule, Slot, Device — booking/practitioner discovery surfaces
• Terminology — ValueSet/$expand + CodeSystem read

Plus Latin-America-specific extensions for naming conventions, blood type, ethnicity, private insurance, cancellation audit trails, and the regulatory metadata required by NOM-024-SSA3 in Mexico.

Version

0.1.0. The published GET /fhir/R4/metadata CapabilityStatement on the Public API is kept in lockstep with this IG; partner systems should compare the API's software.version against the version in History.

Where to start

• Patient Mapping — most common resource, demonstrates the multi-surname name model (HuliSecondLastname) and identifier patterns (CURP, RFC, INE for MX).
• Appointment Mapping — cancellation audit extension and confirmation-status work flows.
• Encounter Mapping — clinical consultation, including the writable Plan section (diagnosis rank, diagnostic impression, follow-up plan as contained resources).
• MedicationRequest Mapping and ServiceRequest Mapping — the writable clinical Plan orders (prescriptions and study/lab orders); both BAA-gated.
• Composition Mapping and DocumentReference Mapping — the clinical-note projection of an Encounter and the patient document ($upload) surface; both BAA-gated.
• HealthcareService Mapping — the org-service identity clients copy onto Appointment.serviceType, plus the Location, PractitionerRole, Schedule & Slot, and Device discovery surfaces.
• Extensions — full list of Huli-defined extensions.
• Terminology — bound value sets, code systems, and the ValueSet/$expand terminology service.

API

Authentication uses SMART on FHIR client_credentials + private_key_jwt. Discovery: GET https://api.huli.io/.well-known/smart-configuration.

Contract

This IG is the wire contract for the Huli Public FHIR R4 API. Profiles, extensions, terminology, and the CapabilityStatement published here describe exactly what the API at https://api.huli.io/fhir/R4 produces and accepts. Partner implementations should validate against these artifacts.

Data handling and compliance

The resources described in this IG carry protected health information (PHI): national identifiers (CURP, INE, CED, DIMEX, DPI, passport), dates of birth, addresses, blood type, private-insurance details, and ICD-10-coded conditions. Integrators are responsible for handling that data under the regimes that apply to their deployment:

• HIPAA (US-touching deployments) — minimum-necessary access, audit logging of access and disclosure, breach-notification obligations. Integrators acting as Business Associates must execute a BAA with the covered entity they serve before consuming this API.
• NOM-024-SSA3 (México) — the Mexican standard for electronic clinical information systems. CURP, biological sex, and birth-date are NOM-024 required fields; integrators must persist them with tamper-evident audit trails, support patient-initiated rectification, and respect the retention windows the standard defines for clinical records.
• Country-specific data-protection law — LFPDPPP (México), LPDP (Costa Rica), and the equivalent regimes in each LATAM country Huli serves impose consent, retention, cross-border-transfer, and data-subject-rights obligations on third-party integrators. The IG does not enumerate these — integrators must comply locally.

Minimum integrator obligations when consuming this API:

1. Do not log identifiers in plaintext. CURP, INE, CED, DIMEX, DPI, and passport numbers are PHI; request/response logs that capture them must be encrypted at rest, access-controlled, and retained no longer than your compliance regime requires.
2. Apply minimum-necessary scope. SMART scopes (system/Patient.r, system/Observation.r, etc.) gate what the API will return — request only what your workflow requires, not the union of everything you might ever need.
3. Respect data-subject rights. If a Huli-managed patient exercises a rectification or deletion right against Huli, integrators may receive updated Patient.meta.lastUpdated and Patient.active=false signals the next time they fetch — re-sync rather than retaining the prior snapshot indefinitely.
4. Encrypt in transit. The API is TLS-only; integrators must reject any redirect that drops to HTTP and must validate the published server certificate (no certificate pinning is required, but TLS verification must not be disabled).
5. Maintain your own audit trail. Huli audits every read and write through the API; integrators should mirror that with their own per-request log of who-accessed-what-when, retained according to the regime they operate under.

This section is a checklist, not a substitute for legal counsel; consult your compliance team before going live against the production API.