What is DocumentReference?

DocumentReference is a metadata resource that describes and locates a document. It does not contain the document bytes — it points to where they are stored (typically the file returned by /files/upload).

API convention: the patient reference is sent as a flat string id (subjectId). Author and authenticator references keep the standard FHIR reference shape. All resource ids are raw UUIDs (v4).

Create a DocumentReference

curl -X POST https://api.esus.health/fhir/DocumentReference \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/fhir+json" \
  -d '{
    "status": "current",
    "docStatus": "final",
    "type": {
      "coding": [{
        "system": "http://loinc.org",
        "code": "34117-2",
        "display": "History and physical note"
      }]
    },
    "category": [{
      "coding": [{
        "system": "http://hl7.org/fhir/document-class",
        "code": "clinical-notes",
        "display": "Clinical Notes"
      }]
    }],
    "subjectId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "date": "2026-04-21T10:30:00Z",
    "author": [{
      "reference": "Practitioner/a7b1c2d3-e4f5-6789-abcd-ef0123456789",
      "display": "Dr. Sarah Johnson"
    }],
    "description": "Annual wellness examination",
    "content": [{
      "attachment": {
        "contentType": "application/pdf",
        "url": "https://api.esus.health/files/{orgId}/{fileId}",
        "title": "Annual Wellness Exam.pdf",
        "creation": "2026-04-21T10:30:00Z"
      }
    }],
    "context": {
      "encounter": [
        { "reference": "Encounter/c1a2e3d4-5b6f-7890-abcd-ef1234567890" }
      ],
      "period": {
        "start": "2026-04-21T09:00:00Z",
        "end": "2026-04-21T10:00:00Z"
      }
    }
  }'

The content.attachment.url should point to a file that was previously uploaded via /files/upload. See the next page for the upload flow.

DocumentReference Status

Document Content Types (examples)

Search Documents

# All documents for a patient
curl "https://api.esus.health/fhir/DocumentReference?patient=3fa85f64-5717-4562-b3fc-2c963f66afa6" \
  -H "Authorization: Bearer YOUR_TOKEN"

# Clinical notes only
curl "https://api.esus.health/fhir/DocumentReference?patient=3fa85f64-5717-4562-b3fc-2c963f66afa6&category=clinical-notes" \
  -H "Authorization: Bearer YOUR_TOKEN"

# By date range
curl "https://api.esus.health/fhir/DocumentReference?patient=3fa85f64-5717-4562-b3fc-2c963f66afa6&date=ge2026-01-01" \
  -H "Authorization: Bearer YOUR_TOKEN"

Reading and Downloading a Document

# Read the metadata
curl "https://api.esus.health/fhir/DocumentReference/c1a2e3d4-5b6f-7890-abcd-ef1234567890" \
  -H "Authorization: Bearer YOUR_TOKEN"

# Fetch the actual file via the URL in content[0].attachment.url
curl "https://api.esus.health/files/{orgId}/{fileId}" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  --output downloaded.pdf