Composition

Composition is the FHIR resource used to build a structured clinical document — a discharge summary, a referral letter, a care-plan package, or any narrative that groups sections together and references the underlying clinical data.

Note: ESUS does not implement the DocumentManifest resource. When you want to group related documents, use a Composition (optionally packaged in a FHIR Bundle of type document) and reference the relevant DocumentReference, DiagnosticReport, CarePlan, etc. from its sections.

Create a Composition

curl -X POST https://api.esus.health/fhir/Composition \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/fhir+json" \
  -d '{
    "status": "final",
    "type": {
      "coding": [{
        "system": "http://loinc.org",
        "code": "34117-2",
        "display": "History and physical note"
      }]
    },
    "subjectId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "encounterId": "c1a2e3d4-5b6f-7890-abcd-ef1234567890",
    "date": "2026-04-21T10:30:00Z",
    "author": [{
      "reference": "Practitioner/a7b1c2d3-e4f5-6789-abcd-ef0123456789",
      "display": "Dr. Sarah Johnson"
    }],
    "title": "Annual wellness examination",
    "section": [
      {
        "title": "History and Physical",
        "entry": [
          { "reference": "DocumentReference/aa11bb22-cc33-dd44-ee55-ff6677889900" }
        ]
      },
      {
        "title": "Lab Results",
        "entry": [
          { "reference": "DiagnosticReport/bb22cc33-dd44-ee55-ff66-778899001122" }
        ]
      },
      {
        "title": "ECG Report",
        "entry": [
          { "reference": "DocumentReference/cc33dd44-ee55-ff66-7788-990011223344" }
        ]
      }
    ]
  }'

Composition Status

Use Cases

Care-Plan Package

curl -X POST https://api.esus.health/fhir/Composition \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/fhir+json" \
  -d '{
    "status": "final",
    "type": { "coding": [{ "code": "care-plan", "display": "Care Plan" }] },
    "subjectId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "title": "Diabetes management care plan",
    "section": [
      { "title": "Care Plan", "entry": [{ "reference": "CarePlan/aa11bb22-cc33-dd44-ee55-ff6677889900" }] },
      { "title": "Visit Summary", "entry": [{ "reference": "DocumentReference/bb22cc33-dd44-ee55-ff66-778899001122" }] },
      { "title": "Care Instructions", "entry": [{ "reference": "DocumentReference/cc33dd44-ee55-ff66-7788-990011223344" }] }
    ]
  }'

Referral Package

curl -X POST https://api.esus.health/fhir/Composition \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/fhir+json" \
  -d '{
    "status": "final",
    "type": { "coding": [{ "code": "referral", "display": "Referral Package" }] },
    "subjectId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "title": "Cardiology referral package",
    "section": [
      { "title": "Referral", "entry": [{ "reference": "ServiceRequest/aa11bb22-cc33-dd44-ee55-ff6677889900" }] },
      { "title": "Cover letter", "entry": [{ "reference": "DocumentReference/bb22cc33-dd44-ee55-ff66-778899001122" }] },
      { "title": "Echocardiogram", "entry": [{ "reference": "DiagnosticReport/cc33dd44-ee55-ff66-7788-990011223344" }] }
    ]
  }'

Search

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

# Compositions by type
curl "https://api.esus.health/fhir/Composition?patient=3fa85f64-5717-4562-b3fc-2c963f66afa6&type=care-plan" \
  -H "Authorization: Bearer YOUR_TOKEN"