---
title: "Upload a document to be ingested into Zus as FHIR resources."
method: POST
path: "/upload"
tags: ["Upload Document"]
---

# Upload a document to be ingested into Zus as FHIR resources.

`POST /upload`

## Request

- Base URL: `https://data-transformer.sandbox.zusapi.com`
- URL: `https://data-transformer.sandbox.zusapi.com/upload`
- Auth: HTTP bearer

Use this endpoint to upload clinical documents to be transformed into FHIR resources and stored in Zus. Accepts PDF and CCDA formats.

## Request body

- union
  - UploadRequestCDA
    - `data` object, required
      - `type` 'data-transformer/upload', required: The JSON:API type of the data being uploaded.
      - `attributes` object, required
        - `documentData` string, byte, required: Base64 encoded CCDA to be transformed into FHIR resources.
        - `documentMediaType` string, required: The media type of the document being uploaded.
      - `relationships` union
        - PatientRelationship
          - `patient` object: The patient that the document is describing. This must be a patient in the Zus FHIR store.
            - `data` object, required
              - …
        - BuilderRelationship
          - `builder` object: The builder the resources parsed from document should end up as an owner.
            - `data` object, required
              - …
  - UploadRequestPDF
    - `data` object, required
      - `type` 'data-transformer/upload', required: The JSON:API type of the data being uploaded.
      - `attributes` object, required
        - `documentData` string, byte, required: Base64 encoded PDF to be transformed into FHIR resources.
        - `documentMediaType` string, required: The media type of the document being uploaded.
        - `documentPeriodStart` union, required: The start of the period of time that the document covers.
          - string, date-time
          - string, date
        - `documentPeriodEnd` union, required: The end of the period of time that the document covers.
          - string, date-time
          - string, date
        - `documentClass` string, required: The class of the document being uploaded. Must match one of the codes in ValueSet https://hl7.org/fhir/r4/valueset-c80-doc-typecodes.html.
        - `documentPracticeSetting` string: The practice setting of the document being uploaded. Must match one of the codes in ValueSet http://hl7.org/fhir/ValueSet/c80-practice-codes.
        - `documentFacility` string: The facility that the document is associated with. Must match one of the codes in ValueSet https://hl7.org/fhir/valueset-c80-facilitycodes.html.
        - `documentDescription` string: A description of the document being uploaded. This will be the document's Title in the ZAP.
        - `documentAuthor` string: The author of the document being uploaded.
      - `relationships` PatientRelationship, required
        - `patient` object: The patient that the document is describing. This must be a patient in the Zus FHIR store.
          - `data` object, required
            - `type` 'fhir/Patient', required: The JSON:API type of the patient.
            - `id` string, uuid, required: The FHIR resource id of the patient in the Zus FHIR store

## Response `201`

Upload has been successfully started.

- UploadResponse
  - `data` object, required
    - `type` 'data-transformer/upload', required: The JSON:API type of the data being uploaded.
    - `id` string, uuid: The unique identifier for the upload.
    - `attributes` object, required
      - `documentMediaType` 'application/xml' | 'application/pdf', required: The media type of the document being uploaded.
      - `documentPeriodStart` union: The start of the period of time that the document covers.
        - string, date-time
        - string, date
      - `documentPeriodEnd` string: The class of the document being uploaded. Must match one of the codes in ValueSet https://hl7.org/fhir/r4/valueset-c80-doc-typecodes.html.
      - `documentClass` union: The end of the period of time that the document covers.
        - string, date-time
        - string, date
      - `documentPracticeSetting` string: The practice setting of the document being uploaded. Must match one of the codes in ValueSet http://hl7.org/fhir/ValueSet/c80-practice-codes.
      - `documentFacility` string: The facility that the document is associated with. Must match one of the codes in ValueSet https://hl7.org/fhir/valueset-c80-facilitycodes.html.
      - `documentDescription` string: A description of the document being uploaded. This will be the document's Title in the ZAP.
      - `documentAuthor` string: The author of the document being uploaded.
      - `builderId` string, uuid, required: The unique id of the builder that the resources will be associated with.
    - `relationships` PatientRelationship
      - `patient` object: The patient that the document is describing. This must be a patient in the Zus FHIR store.
        - `data` object, required
          - `type` 'fhir/Patient', required: The JSON:API type of the patient.
          - `id` string, uuid, required: The FHIR resource id of the patient in the Zus FHIR store

## Other responses

- `400`: Something is wrong with the request.
- `401`: Unauthorized.
- `403`: Forbidden.
- `404`: Requested resource not found.
- `429`: Request ratelimited.
- `500`: Something went wrong on our end.

---

[API](https://skmtc.dev/zushealth/apis/data-transformer-api.md) - [All operations](https://skmtc.dev/zushealth/apis/data-transformer-api/llms.txt) - [OpenAPI document](https://skmtc.dev/zushealth/apis/data-transformer-api/revisions/0e2734f9da8a?raw)