Ingesting CDA Documents into Zus

Introduction

This documentation shows you how to submit a Clinical Document Architecture (CDA) file via API to the Zus platform. Zus transforms CDAs into FHIR resources and stores them in the platform. 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 CDA 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 CDA: You must encode your CDA as Base64 before transmitting to Zus. We list a few example encoding methods.
  • Python Script Example: Encoding and Decoding Base64 in Python
  • Ubuntu, OSX, Linux Script: Base64 Encode and Decode from Command Line
  • Windows Powershell Script: Powershell Base64 Encoding
    ✋ Make sure you're running a secure Base64-encoding tool that complies with your organization's security requirements. Do not use online tools that are not HIPAA-compliant.

Send the Encoded Document

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

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

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

Body Breakdown:

Items that should be replaced with your data are indicated with a double asterisk (**).

• 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
• 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

Send the request

The API will conduct basic validation on your payload, including:

• That your base64-encoded payload is valid XML
• If a FHIR Patient resource is referenced in the payload, 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 transform the data in your CDA into 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 CDA that you just submitted (most likely the most recent Binary).

View the Binary resource

To view the resources created from your submitted CDA, 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"
        },
        "relationships": {
            "builder": {
                "data": {
                    "type": "auth/builder",
                    "id": "<builder-id>"
                }
            }
        }
    }
}