SOAP Report
For product owners and partners: Use this page to understand how SOAP Reports are exposed in the MediKIT API and how this supports referral and care-continuity workflows.
For architects and developers: Use this page to implement patient-scoped SOAP Report retrieval with the correct
Compositionquery shape, scope, and filtering rules.
SOAP Reports (SOEP consultation reports in Dutch) are exposed as FHIR R4 Composition resources in a patient context.
This guide uses SOAP Report as the canonical term to distinguish Composition-based reporting from SOEP-style Observation entries.
This is intended for structured consultation reporting use cases where integrators need narrative + coded context from GP encounters without bespoke HIS integrations.
Where feasible, these Composition resources are modeled to align as closely as possible with relevant Dutch ZIB definitions (MEDMIJ).
What this endpoint is for
Use Composition SOAP Report search when your product needs consultation reporting such as:
- referral context for downstream care providers
- timeline views in patient-facing applications
- care-continuity handovers between systems
Endpoint map
| Use case | Endpoint | Notes |
|---|---|---|
| Search SOAP Reports | GET /v2/{organizationId}/fhir/R4/Patient/{patientId}/Composition | Requires type=http://loinc.org|67781-5 |
Required access and parameters
Required scope
composition.read
Required query parameter
| Parameter | Required | Allowed value |
|---|---|---|
type | Yes | http://loinc.org|67781-5 |
If type is missing or uses a different value, the API returns a validation OperationOutcome (422).
Supported optional filters
| Parameter | Purpose | Allowed values |
|---|---|---|
_include | Include related resources in the same Bundle | Composition:encounter |
encounter:Encounter.episode-of-care | Restrict SOAP entries to one episode of care | EpisodeOfCare logical ID |
Request examples
curl -s \
-H "Authorization: ******" \
"https://dev-api.medikit.nl/v2/{organizationId}/fhir/R4/Patient/{patientId}/Composition?type=http://loinc.org|67781-5"
With encounter include:
curl -s \
-H "Authorization: ******" \
"https://dev-api.medikit.nl/v2/{organizationId}/fhir/R4/Patient/{patientId}/Composition?type=http://loinc.org|67781-5&_include=Composition:encounter"
With episode-of-care filter:
curl -s \
-H "Authorization: ******" \
"https://dev-api.medikit.nl/v2/{organizationId}/fhir/R4/Patient/{patientId}/Composition?type=http://loinc.org|67781-5&encounter:Encounter.episode-of-care={episodeOfCareId}"
Response shape
Successful responses return a FHIR R4 Bundle (type: searchset) containing SOAP Composition resources for the requested patient context.
Error behavior
| Status | Scenario |
|---|---|
403 | Client lacks composition.read scope or access to the requested patient context |
422 | Missing or unsupported query parameters (for example invalid type or unsupported _include) |
What is supported and what is not
| Supported today | Not supported |
|---|---|
Patient-scoped SOAP Composition search with strict type filter | Generic Composition search without type |
| Optional include of encounter context | Arbitrary _include values |
| Optional filter by episode of care | Generic create/update/delete for Composition |