Product Guide

Ingesting Documents into Zus

Suggest Edits

Introduction

This documentation shows you how to submit a CDA or PDF document via API to the Zus platform. Zus transforms stores these documents in our platform and, in the case of CDAs, transforms them into discrete FHIR resources. This data is then available in the Zus App, Snowflake, and for contribution back to the EHR networks (CommonWell and Carequality).

Prepare Your Document

  • Generate the document:
    • CDA documents should be in XML format and conform to HL7 C-CDA 2.1 standards; this HL7 site provides common templates. Although Continuity of Care Documents (CCDs) and Progress Notes are the templates we see most frequently, we accept other summary templates well.
  • Base64-encode the document: You must encode your CDAs and PDFs as Base64 before transmitting to Zus. We list a few example encoding methods.

Upload the Encoded Document

After your document has been encoded, it is ready for transport to Zus via our /upload endpoint.

Uploading CDAs

URL: POST https://data-transformer.zusapi.com/upload

🔗 In Postman

{
    "data": {
        "type": "data-transformer/upload",
        "attributes": {
          "documentData": "<base64-encoded-file>",
          "documentMediaType": "application/xml",
          "priority": false
        },
        "relationships": {
            "patient": {
                "data": {
                    "type": "fhir/Patient",
                    "id": "<patient-id>"
                }
            }
        }
    }
}

Body Breakdown:

Required items are indicated with a 🌟.

  • 🌟 type: specifies the type of job, which in this case is always data-transformer/upload.
  • 🌟 attributes: contains all the required fields for the upload job.
    • 🌟 documentData: the b64 encoded string that represents the file to be uploaded.
    • 🌟 documentMediaType: the MIME Type of the file being uploaded. For a CDA this should always be application/xml
    • priority: when set to false, indicates that the API should use Zus's bulk ingestion process. Requests that are set to true or not set will be throttled at a rate of 30 uploads/minute.
  • relationships: Optionally links the upload job to existing entities, in this case a FHIR Patient resource. If you don't supply a patient reference, we will generate a new Patient resource using the demographics in the document.
    • patient: defines this upload job as relating to an existing patient
      • type: defines the type of FHIR resource, in this instance a patient
      • id: the identification number or string associated with the patient

Uploading PDFs

URL: POST https://data-transformer.zusapi.com/upload

🔗 In Postman

{
    "data": {
        "type": "data-transformer/upload",
        "attributes": {
          "documentData": "<base64-encoded-file>",
          "documentMediaType": "application/pdf",
          "documentPeriodStart": "<period-start-date>",
          "documentPeriodEnd":"<period-end-date>",
          "documentClass": "<LOINC-document-class>",
          "priority": false
        },
        "relationships": {
            "patient": {
                "data": {
                    "type": "fhir/Patient",
                    "id": "<patient-id>"
                }
            }
        }
    }
}

Body Breakdown:

Required items are indicated with a 🌟.

  • 🌟 type: specifies the type of job, which in this case is always data-transformer/upload.
  • 🌟 attributes: contains required and recommended fields for the upload job.
    • 🌟 documentData: the b64 encoded string that represents the file to be uploaded.
    • 🌟 documentMediaType: the MIME Type of the file being uploaded. For PDFs, this should always be application/pdf
    • 🌟 documentPeriodStart: the start date of the encounter or treatment period documented in this PDF
    • 🌟 documentPeriodStart: the end date of the encounter or treatment period documented in this PDF
    • 🌟 documentClass: classification that helps requestors understand what this document is (e.g., Discharge Summary, Progress Note). Must be a LOINC code from this value set. If you can't identify a LOINC code that applies, use 34765-8.
    • priority: when set to false, indicates that the API should use Zus's bulk ingestion process. Requests that are set to true or not set will be throttled at a rate of 30 uploads/minute.
    • ℹ️ In an upcoming release, we will recommend (but not require) that users submitting PDFs also supply practiceSetting and facilityType information.
  • 🌟 relationships: Links the upload job to existing entities, in this case a FHIR Patient resource.
    • 🌟 patient: defines this upload job as relating to an existing patient
      • 🌟 type: defines the type of FHIR resource, in this instance a patient
      • 🌟 id: the identification number or string associated with the patient

Validation and Submission

The API will conduct basic validation on your payload. For CDAs, this includes:

  • Validation that your base64-encoded payload is valid XML
  • If a FHIR Patient resource is referenced in the payload, validation that it matches patient demographics in the CDA

If your request fails one or both of these checks, the API will error.

If your request passes these checks and is successful, the API will respond with an HTTP 201status code. As you build to this API, we recommend logging the ID provided in the request response in case you need assistance with a submission. 

{
    "data": {
        "type": "data-transformer/upload",
        "id": "XXXXXXX3-2XXXXXf-4XXXX",
        "attributes": {
            "patientID": "cXXXXX-XXXXXX-XXXX-XXXXX",
            "documentMediaType": "application/xml"
        }
    }
}

What Happens Now

Zus will store your data as FHIR resources that are available through the ODS APIs and through Snowflake.

How to Verify Data

After submission you can verify the processed data in FHIRPlace. On average, your data should be written and available to view within 10 minutes, however in some instances data loaded in production during peak processing times may take longer can take. To view your data, log in to FHIRPlace, navigate to the relevant patient's records, and review the newly created resources.

Viewing the generated resources in FHIRPlace

Set FHIRplace to filter on your patient's UPID and navigate to the Binary resource type in the left-hand pane. View the Binary documents associated with the patient and select the binary from the list corresponding with the document that you just submitted (most likely the most recent Binary).


View the Binary resource


To view the resources created from your submitted document, navigate to the Provenance History tab.

If the FHIR data you expect to see does not appear in the platform contact our Support team.

Cross-Builder Use

If you have a cross-builder grant you can use this endpoint to write data to Zus on behalf of the builders whose accounts you manage. To do so, update the body of the call to use the builder relationship.

❗If you supply a patient-ID, the platform will automatically associate this document with the builder that owns that patient. The builder relationship is only relevant if you aren't associating documents with an existing patient but want to make sure they end up in a specific builder whose data you manage.

{
    "data": {
        "type": "data-transformer/upload",
        "attributes": {
          "documentData": "<base64-encoded-file>",
          "documentMediaType": "application/xml",
          "priority": false
        },
        "relationships": {
            "builder": {
                "data": {
                    "type": "auth/builder",
                    "id": "<builder-id>"
                }
            }
        }
    }
}

Updated about 2 months ago