> ## Documentation Index
> Fetch the complete documentation index at: https://docs.metriport.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Upload Document

> Creates a DocumentReference and returns its ID and a URL to use for a medical document upload to our servers.

This endpoint returns the DocumentReference ID and a URL to enable you to upload your patients' medical documents, making them available to other HIEs.

## Overview

To use this endpoint, you will need to follow these steps:

1. Create a `DocumentReference` to describe the document that's being uploaded (see sections below for details on the expected fields and format).

2. Execute the endpoint and receive a URL to use for the document upload.

3. Upload the document by executing a `PUT` request using the `URL` with a `Content-Length` header specifying the size of the document.

<Warning>Uploads are limited to 50MB per file.</Warning>

## Query Params

<ParamField query="patientId" type="string" required>
  The ID of the Patient.
</ParamField>

## Body

A FHIR [DocumentReference](/medical-api/fhir/resources/documentreference).

<ParamField body="type" type="CodeableConcept" required>
  A [CodeableConcept](/medical-api/fhir/data-types/codeableconcept) of the document type.

  <Expandable title="Type properties">
    <ParamField body="text" type="string" required>
      Plain text representation of the document kind - for example `Burn management Hospital Progress note`
    </ParamField>

    <ParamField body="coding" type="Coding[]">
      A [Coding](/medical-api/fhir/data-types/coding) property, which is a reference to a code defined by a terminology system (such as [LOINC](https://loinc.org/)) - for example `[{ code: "100556-0", system: "http://loinc.org", display: "Burn management Hospital Progress note"}]`
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="description" type="string" required>
  A brief description of the document - for example `Discharge Summary`.
</ParamField>

<ParamField body="context" type="DocumentReferenceContext[]" required>
  Context of the document content.

  <Expandable title="Context properties">
    <ParamField body="period" type="Period" required>
      A time [Period](/medical-api/fhir/data-types/period) property including ISO 8601 timestamp(s) - for example
      `{ start: "2023-10-10T14:14:17Z" },`
    </ParamField>

    <ParamField body="facilityType" type="CodeableConcept">
      An object that represents the facility type.

      <Expandable title="Facility type properties">
        <ParamField body="text" type="string">
          Plain text with the facility name and type - for example `John Snow Clinic - Acute Care Centre`.
        </ParamField>
      </Expandable>
    </ParamField>
  </Expandable>
</ParamField>

<Tip>
  Note that you do not need to include a Patient or Organization resource in the contained property,
  as those will be inferred on our end - if you do, they will be overwritten.
</Tip>

Example Payload:

```json theme={null}
{
  description: "Third degree wrist burn treatment",
  type: {
    text: "Burn management Hospital Progress note",
    coding: [
      {
        code: "100556-0",
        system: "http://loinc.org",
        display: "Burn management Hospital Progress note"
      },
    ],
  },
  context: {
    period: {
      start: "2023-10-10T14:14:17Z",
      end: "2023-10-10T15:30:30Z",
    },
    facilityType: {
      text: "John Snow Clinic - Acute Care Centre",
    },
  },
};
```

## Response

The DocumentReference ID and a URL to be used for file upload.

```json theme={null}
{
  "documentReferenceId": "<DocumentReference-ID-string>",
  "uploadUrl": "<url-string>"
}
```

<ResponseExample>
  ```javascript Metriport SDK theme={null}
  import { MetriportMedicalApi } from "@metriport/api-sdk";
  import axios from "axios";

  const metriport = new MetriportMedicalApi("YOUR_API_KEY");
  const docRef: Partial<DocumentReference> = {
    description: "Third degree wrist burn treatment",
    type: {
      text: "Burn management Hospital Progress note",
      coding: [
        {
          code: "100556-0",
          system: "http://loinc.org",
          display: "Burn management Hospital Progress note",
        },
      ],
    },
    context: {
      period: {
        start: "2023-10-10T14:14:17Z",
      },
      facilityType: {
        text: "My Clinic Name - Acute Care",
      },
    },
  };

  const resp = await metriport.createDocumentReference("018a80c4-292a-7486-a1234-76yuhe23yu14", docRef);

  // Upload the document using this url in a PUT request, something along these lines for a PDF:

  // const fileContent = <medical-document-document-contents>;
  // await axios.put(resp.uploadUrl, fileContent, {
  //     headers: {
  //         "Content-Length": <size-in-bytes>,
  //         "Content-Type": "application/pdf",
  //     },
  // });
  ```
</ResponseExample>