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 (supports FHIR date prefixes `eq`, `gt`, `lt`, `ge`, `le`, `ne`)
`author`	Document author
`_count`	Page size
`_offset`	Pagination offset
`_sort`	Column to sort by (allowlisted)

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"

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.