Zus stores data in our operational data store according to the Fast Healthcare Interoperability Resources Release 4 (FHIR R4) specification, maintained by the HL7 organization (HL7). We offer a robust FHIR REST API, as detailed in our API Reference.

Authentication

The Zus FHIR REST APIs support the same HTTP Authorization token used throughout Zus APIs. See Authenticating for API Access for instructions on obtaining a bearer token.

FHIR R4 Validation Exceptions

📘

Zus FHIR validation logic is subject to change - Any changes to FHIR validation logic will be announced to customers via a release note.

Zus stores and accepts data according to the FHIR R4 specification, but our FHIR API permits a small set of intentional exceptions from strict R4 instance validation. These exceptions exist to accommodate real-world data variability from EHRs, networks, and partner systems while still rejecting structurally broken resources.

This affects both writers and readers. If you are writing data to Zus, a resource that Zus accepts will not necessarily pass a strict R4 validator elsewhere. If you are reading data from the Zus FHIR API, the data you receive may include values, structures, and codes that originated upstream and do not strictly conform to R4. Systems forwarding Zus data to strict R4 consumers should plan for a normalization step.

Shape and structural leniency

The following structural conditions are accepted by the Zus FHIR API even though strict R4 validation would reject them:

• Empty objects, empty arrays, and null values. Fields containing {}, [], null, or a null element inside an array are tolerated wherever R4 would otherwise require an object, array, or simple value.
• Empty narrative content. A Resource.text.div with no non-whitespace content is accepted.

Terminology leniency

Zus does not enforce most value set bindings or code system membership. This is a deliberate tradeoff: codes and code systems from upstream sources (EHRs, HIEs, national networks) vary widely in conformance, and rejecting them at the boundary would discard clinically meaningful data. Specifically:

• Unknown codes are accepted for nearly all value sets. A code that is not present in its bound value set will not produce a validation error. The single exception is the administrative-gender value set (http://hl7.org/fhir/ValueSet/administrative-gender), which is strictly enforced because it is small, stable, and used pervasively across the platform — Patient.gender, Practitioner.gender, etc. must use one of male, female, other, or unknown (lowercase).
• Unknown code systems are accepted. A Coding.system that the validator does not recognize will not cause the resource to be rejected.
• Unknown profiles are not enforced. A meta.profile reference to a profile the validator cannot resolve will not cause the resource to be rejected, and the resource will not be checked against that profile's constraints.

A practical consequence of the above: status fields such as Appointment.status and Encounter.status will accept values outside the R4 required value set (e.g. "started") without error. If you need strict status conformance for downstream consumers, validate at your own application layer.

Resource-specific behavior

Some resources receive special handling:

• DocumentReference.text.div is not validated. Narrative content is treated as opaque; you may submit any value, including malformed XHTML. Per the FHIR specification, narrative is a generated, human-readable summary and is not the primary source of truth for the resource — consumers should not depend on its structural validity.
• Binary.data is not validated. The base64 payload is stored as submitted and is not run through instance validation.
• DELETE operations skip validation entirely.