Document Searching · Esus Health

Supported Search Surface

Document-related resources (DocumentReference, Composition, DiagnosticReport, Media) share the FHIR search pattern: filter by patient, date, type, category, status, and author; paginate with _count and _offset; sort with _sort.

Full-text search over attached file contents, chained search, and the FHIR Parameters-based batch operations ($batch, $export on DocumentReference) are not part of the current surface. Bulk export of patient data is available via the platform-wide Bulk Export (see Platform Features).

Common Search Parameters

Parameter	Description
`patient`	Filter by patient UUID
`status`	Document status
`type`	Document type (e.g. a LOINC code)
`category`	Document category
`date`	Document date (exact-day match; FHIR prefixes `ge`/`le`/`gt`/etc. are not applied)
`author`	Document author
`_count`	Page size
`_offset`	Pagination offset
`_sort`	Column to sort by (allowlisted; includes `date`, so `-date` works)
`_include`	Pull referenced resources into the same bundle (e.g. `_include=DocumentReference:patient`)
`_revinclude`	Pull resources that reference the results

Filter Examples

Radiological Images by Type

curl "https://api.esus.health/fhir/DocumentReference?patient=3fa85f64-5717-4562-b3fc-2c963f66afa6&type=http://loinc.org|79378-7" \
  -H "Authorization: Bearer YOUR_TOKEN"

Discharge Summaries

curl "https://api.esus.health/fhir/DocumentReference?patient=3fa85f64-5717-4562-b3fc-2c963f66afa6&type=http://loinc.org|34105-7" \
  -H "Authorization: Bearer YOUR_TOKEN"

Clinical Notes by Author

curl "https://api.esus.health/fhir/DocumentReference?patient=3fa85f64-5717-4562-b3fc-2c963f66afa6&author=Practitioner/a7b1c2d3-e4f5-6789-abcd-ef0123456789" \
  -H "Authorization: Bearer YOUR_TOKEN"

Document Timeline

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

Lifecycle and Optimistic Concurrency

DocumentReference, DiagnosticReport, and Composition expose the full CRUD lifecycle plus PATCH, and versioning via GET /:id/_history and GET /:id/_history/:vid. Every write returns an ETag header of the form W/"<versionId>"; pass that value in If-Match on PUT/PATCH for optimistic concurrency. If the version does not match, the write is rejected with 412 Precondition Failed.

Subscribing to Document Events

Use the standard Subscription resource to receive webhook callbacks when a matching document is created:

curl -X POST https://api.esus.health/fhir/Subscription \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/fhir+json" \
  -d '{
    "status": "active",
    "reason": "New documents for patient",
    "criteria": "DocumentReference?patient=3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "channel": {
      "type": "rest-hook",
      "endpoint": "https://your-app.example.com/webhooks/documents",
      "payload": "application/fhir+json"
    }
  }'

Privacy and Access Control

Documents respect per-tenant isolation (PostgreSQL RLS), RBAC, ABAC policies, and patient Consent. Search results are filtered to the records the caller is authorized to read — unauthorized documents are never returned and never counted.

Exporting Patient Documents

For large exports (migrations, analytics, patient data requests), use the platform’s Bulk Export — see the Platform Features section for the $export operation at the system level. There is no per-resource $export on DocumentReference.