Changelog

vv1.9.0Breaking

Impossible measurement values are refused

Breaking: yes, for integrations that send 0 on a vital sign, growth, glucose, waist circumference or mean arterial pressure observation, or re-send a stored reading that holds 0. Those writes succeed today and fail with 400.

Changed

  • Observation creates and updates refuse a value of 0 with 400 on a vital sign or growth code (weight, height, head circumference, temperature, heart and respiratory rate, blood pressure, oxygen saturation, BMI), on blood glucose, and on waist circumference (8280-0) and mean arterial pressure (8478-0), which this API files under the laboratory category. Any other laboratory result of 0 is still accepted.
  • A 0 refusal returns an OperationOutcome issue with code value, expressionObservation.valueQuantity.value and HPB-00101 in details, with diagnostics that say 0 is not a real reading.

Migration

  • Do not send 0 to mean "not measured". Omit the observation instead.
vv1.8.0Breaking

A possible duplicate pauses clinical writes

Breaking: yes, for integrations that write clinical data for patients who booked online or through the patient portal. While the clinic reviews a possible duplicate, writes that succeed today fail with 409.

Changed

  • When a patient file was created by an online booking or the patient portal and may be the same person as an existing file, the clinic reviews it before anyone records clinical data. Until then, creates and updates of Encounter, Composition, Observation, MedicationRequest and ServiceRequest on either file are refused with 409 HPB-00154, OperationOutcome.issue.code duplicate. Retrying right away does not help; hold the write. If the clinic keeps the files apart, the same request then succeeds. If it links them («Es el mismo paciente»), both ids are retired and the retry is refused with a 409 conflict (such as HPB-00103); send the write to the surviving patient instead (Patient.link).
  • Branch on issue[0].code: only this refusal is duplicate; other 409s stay conflict and keep their meaning and handling.
  • While a consultation that started before the review is still in progress, writes on that patient go through so it can be completed and closed, except creating another encounter (POST Encounter, or POST Composition, which creates one) or starting a planned one. Cancelling an open encounter is always allowed, and a planned one can be edited while it stays planned.
  • Uploading a DocumentReference is not refused; its automatic extraction waits until the review is done.
  • Rolling out: the refusal applies once Huli enables it on the public API, which follows Patient/$match and Patient.link. Until then these writes are not refused.
vv1.7.0Breaking

Search filters you cannot express are rejected, not ignored

Breaking: yes, for searches that send a malformed patient, encounter, practitioner, _id or Observation status. They used to drop the filter and return every match in the organization; they now fail with 400 HPB-00101.

Added

  • patient, encounter and practitioner accept Patient/{id} (or Encounter/{id}, Practitioner/{id}) and an absolute URL ending in it, as well as the bare id, on Observation, Encounter, Appointment, Composition, DocumentReference, MedicationRequest and ServiceRequest search. Before, GET /fhir/R4/Observation?patient=Patient/<id> returned the observations of every patient.
  • Observation status takes several values separated by commas and matches any of them, and accepts the http://hl7.org/fhir/observation-status|code form.
  • A rejected filter's message names the parameter and the rule it broke, for example Invalid patient parameter: the reference type must be Patient.

Changed

  • A reference that is not an id, names another resource type, carries a version (/_history/n) or lists several values is rejected with 400. So is an _id that is not a single id, and an Observation status with an unknown code or system.
  • On MedicationRequest and ServiceRequest, a malformed patient or encounter is rejected even when the other one is valid. Before, the malformed one was ignored.
  • Observation status=registered matches nothing. Huli never stores that status, and before it returned final observations. unknown also matches nothing.
  • Reference and _id parameters do not take comma-separated lists: _id=<a>,<b> is rejected with 400. Before, the list was ignored and the search returned every resource of the organization.
  • In the OpenAPI document, patient, encounter and practitioner are typed string (no longer format: uuid), since they also take Type/{id} and absolute references. Regenerated clients pass them as strings.
  • With Prefer: handling=lenient, an empty value of a repeated parameter (patient=&patient=<id>, date=&date=ge2026-01-01) no longer hides a later one, for every search parameter. A repeated parameter still uses its first non-empty value.
vv1.6.0Breaking

Recurring edits from a cancelled occurrence are refused

Breaking: yes, for integrations that edit a recurring series through an occurrence that is cancelled or entered-in-error. Those requests used to succeed; they now fail with 422.

Changed

  • PUT /fhir/R5/Appointment/{id}?_recurrenceScope=... with a field edit, sent from an occurrence whose status is cancelled or entered-in-error, is rejected with 422 (business rule) in every scope and changes nothing. Before, all and this-and-following applied the edit to the series. Read the series again and send the edit through an active occurrence.
  • A stale If-Match on the same request is checked first and still answers 409.
  • Occurrences in any other status, including fulfilled and noshow, behave as before.
vv1.5.0Breaking

Observation search: OR-ed codes, and no more ignored categories

Breaking: yes, for searches that send an unrecognized category value. They used to return every observation; they now fail with 400.

Added

  • code takes several values separated by commas and matches any of them: GET /fhir/R4/Observation?patient=<id>&code=29463-7,3141-9 returns both body weights.
  • code accepts the system|code form (http://loinc.org|3141-9). A value with a system matches only observations coded under that system; |code (no system) matches nothing, since every observation carries one.
  • category accepts the system|code form under http://terminology.hl7.org/CodeSystem/observation-category, and several values separated by commas. vital-signs together with laboratory or exam matches every observation.

Changed

  • A category value other than vital-signs, laboratory or exam, or under another system, is rejected with 400 HPB-00101. It used to be ignored, so the search returned every observation.
  • In code and category, more than 100 comma-separated values, an empty value inside the list (code=3141-9,), a value with a second |, or a FHIR \ escape is rejected with 400HPB-00101; the diagnostics name the rule that failed. A parameter sent with no value at all (code=) is still ignored, as FHIR requires.
  • Same on /fhir/R5.
vv1.4.0Breaking

The alternate body-weight code 3141-9 is a vital sign

Breaking: yes, for integrations that read Observation.category or search by category on observations coded LOINC 3141-9.

Changed

  • An Observation with code 3141-9 (body weight, measured) now carries categoryvital-signs instead of laboratory, on read, search, create and update responses and in $everything (R4 and R5). It is the same body weight Huli already plots on the growth chart next to 29463-7.
  • GET /fhir/R4/Observation?category=vital-signs now returns these observations, and category=laboratory and category=exam no longer do. Same on /fhir/R5.
  • No other code changes category, and the resource shape is unchanged.
  • The category is derived at read time, so already-stored observations change category without a new meta.versionId / meta.lastUpdated: a _lastUpdated sync will not see the change. Re-read the 3141-9 observations you keep under laboratory.

To read every body weight

Search each code on its own, code=29463-7 and code=3141-9 (the code parameter takes one code), or use category=vital-signs when you want all vital signs.

vv1.3.0Non-breaking

Observation names its fetus

Breaking: no. Observations without a fetus keep their exact shape.

Added

  • Observation.focus on per-fetus observations in a multiple gestation, on read, search and $everything (R4 and R5): display "Feto A".."Feto F", plus an identifier under https://huli.io/fhir/identifier/fetus valued <pregnancy id>-<letter> when a pregnancy covers the observation's day. Two fetuses' readings of the same code and day are now told apart.
  • focus is read-only: it is ignored on create and update, as before.
  • The identifier is omitted when the fetus letter exceeds the covering pregnancy's fetus count. It is derived at read time: editing the EDD, or resolving or cancelling the pregnancy, changes or removes it without bumping meta.versionId / meta.lastUpdated, so a _lastUpdated sync will not see that change.
vv1.2.0Breaking

Prenatal ultrasound observations require a covering pregnancy

Breaking: yes, for Observation writes under the codes below.

An Observation with one of these codes must now be dated inside one of the patient's pregnancies. create, and an update that moves effectiveDateTime to another day, return 400 when the date falls in no pregnancy, when the patient has none, or when the covering pregnancy carries more than one fetus and the code describes a single fetus. An update that keeps the stored day is accepted as before.

  • Fetal heart rate 55283-6 and 11884-4, amniotic fluid index 11627-7, fetal presentation 11876-0.
  • Ultrasound biometry: 11957-8, 33069-6, 11820-0, 11947-9, 11793-9, 11962-8, 11878-6, 12146-7.
  • Huli codes, declared under https://fhir.huli.ai/CodeSystem/huli-observation: HULI-CERVIX-LEN, HULI-NASAL-BONE, HULI-UT-ARTERY, HULI-PLAC.
vv1.1.0Breaking

Encounters record their location

Breaking: yes, for integrations that create encounters for a practitioner who works at more than one location.

  • Encounter.location is now read and written on R4 and R5. Send location[0].location as a Location/<id> reference to one of the practitioner's locations, listed on PractitionerRole.location (GET /fhir/R4/PractitionerRole?practitioner=<id>).
  • When the practitioner works at exactly one location, or the encounter is bound to an appointment that has a location, location can be omitted: the location is recorded for you. If you do send it with such an appointment, it must be the appointment's location.
  • A create that omits it for a practitioner with several locations, names a location that is not theirs, or names one other than its appointment's, is refused with 422 HPB-00150. A practitioner with no location assigned gets 422 HPB-00151 until an administrator assigns one.
  • Under la normativa (the Mexican regulation) what counts is the practitioner's normativa configuration: a location configured for them is accepted, one that is not is refused with 403 HPB-00141.
  • Changed error code under la normativa: a create that names no location for a practitioner with several configured locations used to be refused with 403 HPB-00141. It is now refused with 422 HPB-00150, as outside la normativa, and naming one of their locations resolves it. HPB-00141 now covers only a location that is not configured for the practitioner.
  • Composition creates follow the same rule, and a Composition has no location element: for a practitioner with several locations, POST /fhir/R4/Composition is refused with 422HPB-00150. Create the Encounter with its location first, then write the note with PUT /fhir/R4/Composition/{encounterId}; a POST always creates a new encounter.
  • The location is create-only: an update naming a different one, or adding one to an encounter recorded without it, is refused with 422.
  • Reads and searches include Encounter.location whenever one was recorded.
vv1.0.0Non-breaking

Huli Public API v1.0 — General Availability

Breaking: no. This is the initial public release.

What ships

FHIR R4 resources

  • Patient — read, search, create, update. Identifiers: CURP, RFC, NSS, INE. Two-surname support via the segundo-apellido extension. Gender mapping: FHIR male/female/other → Huli M/F/I.
  • Appointment — read, search, create, update. Status transitions: booked, cancelled, fulfilled.
  • Encounter — read, search, create, update. Class: ambulatory, emergency, inpatient.
  • Observation — read, search, create, update. Categories: vital-signs, laboratory, exam. LOINC required on write. UCUM validated.
  • Practitioner — read, search (read-only).
  • Organization — read, search (read-only).

Authentication

  • Admin-managed bearer tokens via Practice Settings.
  • SMART backend services (client_credentials + private_key_jwt, RS384).
  • Interactive OAuth Authorization Code + PKCE via app.huli.ai/oauth/authorize.
  • SMART discovery at /fhir/.well-known/smart-configuration.

Rate limiting and audit

  • Per-key and per-organization request ceilings. 429 with Retry-After on limit exceeded.
  • Every authenticated request writes an audit record with 7-year retention (NOM-024 compliance requirement).

huli CLI v1.0

  • huli auth login (interactive OAuth PKCE), huli auth setup (bearer), huli auth status, huli auth token.
  • huli fhir patient|appointment|encounter|observation|practitioner|organization subcommands.
  • huli api get|post|put for raw HTTP access.
  • huli config get|set|list.

Scope system

  • system/<Resource>.<perms> format. Permissions: r (read), s (search), c (create), u (update).
  • Scopes: system/Patient.rs, system/Patient.cru, system/Appointment.rs, system/Appointment.cru, system/Encounter.rs, system/Encounter.cru, system/Observation.rs, system/Observation.cru, system/Practitioner.rs, system/Organization.rs.

Error codes

CodeHTTPMeaning
HPB-00101400Validation error
HPB-00102404Resource not found
HPB-00103409Version conflict
HPB-00104403Insufficient scope
HPB-00105429Rate limit exceeded
HPB-00106401Authentication failed
HPB-00107401Token expired

Known limitations at GA

  • FHIR $export (bulk data access) is not available in v1.
  • Webhook subscriptions are not available in v1.
  • The _include and _revinclude FHIR search parameters are not supported.