Skip to main content

Handling External Files


While the most valuable way of storing healthcare information is in a structured FHIR representation, healthcare apps often need to store and index documents from external systems. For example, patients may submit medical records from other providers in the form of PDF documents.

The DocumentReference resource serves as a "pointer" to these external documents so that they can be indexed and searched. Specifically, DocumentReference.content.attachment can refer to a Binary resource (PDFs, images, videos, etc.), a URL, or anything else supported by the Attachment datatype.

See the DocumentReference API guide for more info.

Example: Creating a DocumentReference for a binary file

This is a similar process to creating a PDF file from a Bot .

First, upload the binary file as a Binary resource. Then, create the corresponding DocumentReference as a pointer.

import { MedplumClient, getReferenceString } from '@medplum/core';

// Create a `Binary` resource with file data
const binary = await medplum.createBinary(data, 'records.pdf', 'application/pdf');

// Create the `DocumentReference` resource
const docReference = await medplum.createResource({
resourceType: 'DocumentReference',
status: 'current',
content: [
attachment: {
title: 'External Records',
url: getReferenceString(binary),

DocumentReference.content.attachment.url can refer to any external url. The Medplum server handles urls of the form "Binary/id" as a special case and converts them to pre-signed URLs at You can read more about pre-signed URLs on the AWS docs