Changelog
vv1.9.0BreakingImpossible 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
Observationcreates and updates refuse a value of0with400on 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 thelaboratorycategory. Any other laboratory result of0is still accepted.- A
0refusal returns anOperationOutcomeissue with codevalue,expressionObservation.valueQuantity.valueandHPB-00101indetails, withdiagnosticsthat say 0 is not a real reading.
Migration
- Do not send
0to mean "not measured". Omit the observation instead.
vv1.8.0BreakingA 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,MedicationRequestandServiceRequeston either file are refused with409 HPB-00154,OperationOutcome.issue.codeduplicate. 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 a409conflict (such asHPB-00103); send the write to the surviving patient instead (Patient.link). - Branch on
issue[0].code: only this refusal isduplicate; other409s stayconflictand 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, orPOST 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
DocumentReferenceis 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/$matchandPatient.link. Until then these writes are not refused.
vv1.7.0BreakingSearch 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,encounterandpractitioneracceptPatient/{id}(orEncounter/{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
statustakes several values separated by commas and matches any of them, and accepts thehttp://hl7.org/fhir/observation-status|codeform. - 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 with400. So is an_idthat is not a single id, and an Observationstatuswith an unknown code or system. - On MedicationRequest and ServiceRequest, a malformed
patientorencounteris rejected even when the other one is valid. Before, the malformed one was ignored. - Observation
status=registeredmatches nothing. Huli never stores that status, and before it returnedfinalobservations.unknownalso matches nothing. - Reference and
_idparameters do not take comma-separated lists:_id=<a>,<b>is rejected with400. Before, the list was ignored and the search returned every resource of the organization. - In the OpenAPI document,
patient,encounterandpractitionerare typedstring(no longerformat: uuid), since they also takeType/{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.0BreakingRecurring 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 iscancelledorentered-in-error, is rejected with422(business rule) in every scope and changes nothing. Before,allandthis-and-followingapplied the edit to the series. Read the series again and send the edit through an active occurrence.- A stale
If-Matchon the same request is checked first and still answers409. - Occurrences in any other status, including
fulfilledandnoshow, behave as before.
vv1.5.0BreakingObservation 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
codetakes several values separated by commas and matches any of them:GET /fhir/R4/Observation?patient=<id>&code=29463-7,3141-9returns both body weights.codeaccepts thesystem|codeform (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.categoryaccepts thesystem|codeform underhttp://terminology.hl7.org/CodeSystem/observation-category, and several values separated by commas.vital-signstogether withlaboratoryorexammatches every observation.
Changed
- A
categoryvalue other thanvital-signs,laboratoryorexam, or under another system, is rejected with400HPB-00101. It used to be ignored, so the search returned every observation. - In
codeandcategory, 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 with400HPB-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.0BreakingThe 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
Observationwith code3141-9(body weight, measured) now carriescategoryvital-signsinstead oflaboratory, 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 to29463-7. GET /fhir/R4/Observation?category=vital-signsnow returns these observations, andcategory=laboratoryandcategory=examno 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_lastUpdatedsync will not see the change. Re-read the3141-9observations you keep underlaboratory.
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-breakingObservation names its fetus
Breaking: no. Observations without a fetus keep their exact shape.
Added
Observation.focuson per-fetus observations in a multiple gestation, on read, search and$everything(R4 and R5):display"Feto A".."Feto F", plus anidentifierunderhttps://huli.io/fhir/identifier/fetusvalued<pregnancy id>-<letter>when a pregnancy covers the observation's day. Two fetuses' readings of the same code and day are now told apart.focusis 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_lastUpdatedsync will not see that change.
vv1.2.0BreakingPrenatal 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-6and11884-4, amniotic fluid index11627-7, fetal presentation11876-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.0BreakingEncounters record their location
Breaking: yes, for integrations that create encounters for a practitioner who works at more than one location.
Encounter.locationis now read and written on R4 and R5. Sendlocation[0].locationas aLocation/<id>reference to one of the practitioner's locations, listed onPractitionerRole.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,
locationcan 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
422HPB-00150. A practitioner with no location assigned gets422HPB-00151until 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
403HPB-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
403HPB-00141. It is now refused with422HPB-00150, as outside la normativa, and naming one of their locations resolves it.HPB-00141now covers only a location that is not configured for the practitioner. Compositioncreates follow the same rule, and aCompositionhas no location element: for a practitioner with several locations,POST /fhir/R4/Compositionis refused with422HPB-00150. Create theEncounterwith its location first, then write the note withPUT /fhir/R4/Composition/{encounterId}; aPOSTalways 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.locationwhenever one was recorded.
vv1.0.0Non-breakingHuli 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 thesegundo-apellidoextension. Gender mapping: FHIRmale/female/other→ HuliM/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.
429withRetry-Afteron 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|organizationsubcommands.huli api get|post|putfor 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
| Code | HTTP | Meaning |
|---|---|---|
HPB-00101 | 400 | Validation error |
HPB-00102 | 404 | Resource not found |
HPB-00103 | 409 | Version conflict |
HPB-00104 | 403 | Insufficient scope |
HPB-00105 | 429 | Rate limit exceeded |
HPB-00106 | 401 | Authentication failed |
HPB-00107 | 401 | Token expired |
Known limitations at GA
- FHIR
$export(bulk data access) is not available in v1. - Webhook subscriptions are not available in v1.
- The
_includeand_revincludeFHIR search parameters are not supported.