The Zus platform implements Fast Healthcare Interoperability Resources v4.0.1 (FHIR R4) APIs.

You can use FHIR REST API operations to manage and search resources in the Zus platform.

Supported FHIR resource types

The API supports the following resource types:

Account, ActivityDefinition, AdverseEvent, AllergyIntolerance, Appointment, AppointmentResponse, AuditEvent, Basic, Binary, BiologicallyDerivedProduct, BodyStructure, CarePlan, CareTeam, CatalogEntry, ChargeItem, ChargeItemDefinition, Claim, ClaimResponse, ClinicalImpression, Communication, CommunicationRequest, Composition, Condition, Consent, Contract, Coverage, CoverageEligibilityRequest, CoverageEligibilityResponse, DetectedIssue, Device, DeviceDefinition, DeviceMetric, DeviceRequest, DeviceUseStatement, DiagnosticReport, DocumentManifest, DocumentReference, EffectEvidenceSynthesis, Encounter, Endpoint, EnrollmentRequest, EnrollmentResponse, EpisodeOfCare, EventDefinition, Evidence, EvidenceVariable, ExampleScenario, ExplanationOfBenefit, FamilyMemberHistory, Flag, Goal, Group, GuidanceResponse, HealthcareService, ImagingStudy, Immunization, ImmunizationEvaluation, ImmunizationRecommendation, InsurancePlan, Invoice, Library, Linkage, List, Location, Measure, MeasureReport, Media, Medication, MedicationAdministration, MedicationDispense, MedicationKnowledge, MedicationRequest, MedicationStatement, MedicinalProduct, MedicinalProductAuthorization, MedicinalProductContraindication, MedicinalProductIndication, MedicinalProductIngredient, MedicinalProductInteraction, MedicinalProductManufactured, MedicinalProductPackaged, MedicinalProductPharmaceutical, MedicinalProductUndesirableEffect, MolecularSequence, NamingSystem, NutritionOrder, Observation, ObservationDefinition, Organization, OrganizationAffiliation, Patient, PaymentNotice, PaymentReconciliation, Person, PlanDefinition, Practitioner, PractitionerRole, Procedure, Provenance, Questionnaire, QuestionnaireResponse, RelatedPerson, RequestGroup, ResearchDefinition, ResearchElementDefinition, ResearchStudy, ResearchSubject, RiskAssessment, RiskEvidenceSynthesis, Schedule, ServiceRequest, Slot, Specimen, SpecimenDefinition, Substance, SubstancePolymer, SubstanceProtein, SubstanceReferenceInformation, SubstanceSpecification, SubstanceSourceMaterial, SupplyDelivery, SupplyRequest, Task, TerminologyCapabilities, TestReport, TestScript, VerificationResult, VisionPrescription

Instance-level read and write operations

The API supports the following instance-level operations:

• POST requests: Allows clients to add new resources to the FHIR server.
• PUT requests: Allows clients to modify existing resources by replacing the current resource representation with a new one. The entire resource must be included in the request body, and the server will update the resource identified by its unique {id}.
• PATCH requests: Allows clients to make partial updates to existing resources identified by {id} using the JSON Patch format.
• DELETE requests: Allows clients to delete an existing resource identified by its unique {id}.
• GET requests: Allows clients to retrieve a resource identified by its unique {id} as well as the search parameters described below.

Bundle requests

Multiple write operations can be processed as a single transaction when grouped into a Bundle. The Bundle.type must indicate that it is a transaction. The Bundle.entry.request.method can be one of PUT, POST, or DELETE. A Bundle can contain at most 100 entries.

Conditional create, update, and delete by identifier

The API supports conditional operations for creating, updating, and deleting a resource that has a given identifier. The identifier is either passed as a header or as a query parameter depending on the operation. The identifier is used to uniquely identify resources and should have the following format [system]|[value]. Please check the documentation for more information.

Version-Aware Write Operations using Zus-If-Match Header

The API supports version-aware conditional operations for updating and patching resources using the Zus-If-Match header to ensure that the client interacts with the most current version of the resource. The Zus-If-Match header uses the ETag (Entity Tag) format to specify the current version of the resource, enabling safe updates and patches based on version matching.

• Version-aware update: PUT /{ResourceType}/{id} updates an existing resource identified by {id} if the server's version matches the ETag provided in the Zus-If-Match header.
• Version-aware patch: PATCH /{ResourceType/{id} Allows clients to make partial updates to existing resources identified by {id} using the JSON Patch format if the server's version matches the ETag provided in the Zus-If-Match header.

Search parameters for Read Operations

Filtering works across all FHIR resources to which a user has access. This includes data from third-party partner networks, other Builders on Zus treating the same patient, and Zus-derived data across all sources. For more information on how the Zus Aggregated Profile (ZAP) works, please see our documentation here.

The API supports the following search parameters on read operations:

Noted changes in behavior

Below is a list of changes as of August 22, 2024 from the previous FHIR API that are not covered elsewhere in this document. Some of these changes are permanent; some are intended to be temporary.

Patient-centric API calls: Previously, making a patient-centric API call required passing a parameter like identifier=<https://zusapi.com/fhir/identifier/universal-id|[upid] on Patient requests, and a patient.identifier parameter for resource types in the ZAP. In the new API, the equivalent parameter is upid=[upid].

Browsing patient resources: Browsing resources by requesting GET/[resourceType] without specifying a UPID will only work for Appointment, Medication, Location, Patient, Practitioner, and Organization resources for the time being. The ability to browse resources without a UPID for other resource types is expected to be added at a later date.

Zus-Account header: Previously, passing the ID of a different builder in the Zus-Account HTTP header would cause the request to be made on behalf of the specified builder (for MSO relationships). The new API does not currently recognize the Zus-Account header. To query for resources owned by a different builder from your own, include the builder query parameter.

Total number of results (count) is not returned: Previously, search results would usually include a count value that described the total number of results that match a query. This value was not always present or accurate. In the new API, count is never returned.

Sorting is not yet supported in search results: Sorting capabilities are expected to be added at a later date.

Cascade delete: Users can no longer cascade deletes to delete all data associated with a given resource. Support for cascade delete is expected to be added at a later date.