eReferral Implementation Guide, published by Riziv-Inami Platform. This guide is not an authorized publication; it is the continuous build for version 2.0.0 built by the FHIR (HL7® FHIR® Standard) CI Build. This version is based on the current content of https://github.com/hl7-be/referral-uhmep/ and changes regularly. See the Directory of published versions

API Operations

This page is a compact operational map of the eReferral API. It is intended as an implementation checklist, not a replacement for the generated FHIR profiles or the eHealth API Portal contract.

Operations are grouped by business objective so an integrator can start from the workflow they need to implement and then identify the FHIR interaction, resource profile, and important rules.

The errors for these operations are maintained in the eReferral API Error Codes workbook. Each detailed operation page links to the workbook and the Error Codes usage guidance.

Detailed Operation Pages

Each operation below has a dedicated page with endpoint details, request payload examples and a sequence diagram.

Area	Operation pages
Medical documents	Create a medical document Consult or search medical documents Complete a medical document Cancel a medical document
Assignment	Assign a care provider Unassign a care provider
Execution	Record execution start Record execution end Record execution interruption Cancel execution
Evaluation	Evaluate a proposal Evaluate a radiology prescription
Multi-call business workflows	Complex operations

Manage a Medical Document

Create A Medical Document

Business objective	Actors	Endpoint	Main resource	Success	Key integration notes
Create a prescription	- Healthcare Professional (Physician) - Organization	POST /ServiceRequest	ServiceRequest	201 Created id in Location	Use intent = order. Identify the template with category[prescriptionType]. Encrypt patient-specific data and free text. eReferral creates a related BeReferralTask.
Create a proposal	- Healthcare Professional (Caregiver) - Organization	POST /ServiceRequest	ServiceRequest	201 Created id in Location	Use intent = proposal. Identify the template with category[prescriptionType]. Encrypt patient-specific data and free text. eReferral creates a related BeReferralTask.

Consult or Search Medical Document(s)

Business objective	Actors	Endpoint	Response	Notes
Read one prescription	- Prescriber - Caregiver - Patient - Organization	GET /ServiceRequest/{referenceId}	ServiceRequest	Applies: visibility rules suspension rules privacy rules access-matrix rules
Read by short code and patient (only available on prescription)	- Prescriber - Caregiver - Patient - Organization	POST /ServiceRequest/_search	Bundle	The short code is a six-character identifier generated by eReferral. When using short code and patient SSIN, eReferral treats O/o as 0 to prevent checksum issues.
Search prescriptions or proposals	- Prescriber - Caregiver - Patient - Organization	POST /ServiceRequest/_search	Bundle	Filters are combined with logical AND. Unknown filters are ignored. Unknown values for defined filters return an empty set.
Read linked tasks	- Prescriber - Caregiver - Patient - Organization	GET /Task?focus={ServiceRequestID}	Bundle	Returns linked BeReferralTask, BePerformerTask, and BeOrganizationTask resources.
Read linked task type	- Prescriber - Caregiver - Patient - Organization	GET /Task?focus={ServiceRequestID}&_profile={profile}	Bundle	Use the referral-task, performer-task, or organization-task profile URI to limit the result.
Read full referral graph	- Prescriber - Caregiver - Patient - Organization	GET /ServiceRequest/{id}/$graph?graph={GraphDefinitionURI}	Bundle	Recommended when the client needs, in one call: the prescription tasks practitioner roles practitioners organizations

Search Filters

Search filters are submitted as application/x-www-form-urlencoded key-value pairs in POST /ServiceRequest/_search.

Filter	Purpose	Status
patient	Filter by patient pseudonym in transit for the eReferral domain.	Active
status	Filter by FHIR ServiceRequest.status; translate from business status first.	Active
statusReason	Filter by additional prescription status information.	Active
_has:Task:focus:status with _profile	Filter by summary execution/referral-task status.	Active
requester	Filter by prescriber. Organization-scoped requester references use PractitionerRole/{SSIN}-{DISCIPLINE}-NIHII-{nihii11Organization}.	Active
_has:Task:focus:owner	Filter by assigned caregiver or assigned organization.	Active
code	Filter by template code using {system}|{code}.	To be replaced by category with system=https://www.ehealth.fgov.be/standards/fhir/terminology/CodeSystem/be-cs-prescription-type
intent	Separate prescriptions (order) from proposals (proposal).	Active
_count	Page size. Default and maximum are currently 25. Higher values return an invalid-count error.	Active
_offset	Zero-based result offset. Defaults to 0.	Active

Cancel a Medical Document

Business objective	Actors	Endpoint	Main resource	Success	Key integration notes
Cancel a prescription	- Patient - Healthcare Professional (Physician) - Organization	PATCH /ServiceRequest	ServiceRequest	200 OK	Replace ServiceRequest.status by revoked and, optionally, add a cancellation reason
Cancel a proposal	- Patient - Healthcare Professional (Caregiver) - Organization	PATCH /ServiceRequest	ServiceRequest	200 OK	Replace ServiceRequest.status by revoked and, optionally, add a cancellation reason

Manage Assignment

Use these operations when the prescription must be assigned to a healthcare professional or to an organization before execution starts.

Assign a Care Provider

Business objective	Actors	Endpoint	Task profile	Success	Key integration notes
Assign a healthcare professional directly	- Patient - Healthcare Professional - Organization when assigning an internal professional	POST /Task	BePerformerTask	201 Created id in Location and response body	Create a task with focus pointing to the prescription. partOf points to the related BeReferralTask. owner references the assigned professional with PractitionerRole
Assign an organization	- Patient - Healthcare Professional - Organization	POST /Task	BeOrganizationTask	201 Created	Create a ready task with focus pointing to the prescription. partOf points to the related BeReferralTask. owner references the assigned organization with PractitionerRole
Assign an internal healthcare professional after organization assignment	Organization with M2M token	POST /Task	BePerformerTask	201 Created	Only the assigned organization can perform this operation. owner references the internal professional with PractitionerRole. basedOn references the existing BeOrganizationTask. The basedOn link is what identifies the professional assignment as internal to the organization assignment.

Unassign a Care Provider

Business objective	Actors	Endpoint	Task profile	Success	Key integration notes
Remove an assignment	Patient Caregiver Organization	DELETE /Task/{executionID}	BePerformerTask or BeOrganizationTask	204 No Content	- Only removable while the execution task is still ready. - The task is deleted and cannot be reused. - Internal performer assignments must remain coherent with the organization assignment they reference.

Manage Execution Progress

Healthcare professionals and organizations do not update the clinical ServiceRequest to record execution. They create or patch task resources.

Record Execution Start

Business objective	Actors	Endpoint	Task status after operation	Success	Key integration notes
Start execution, not assigned yet	- Healthcare Professional - Organization	POST /Task	in-progress	201 Created	- Create a task with only executionPeriod.start. - Start date must not be in the future. - If execution is performed by an internal professional, the organization must link the performer task to the organization task with basedOn.
Start execution, already assigned	- Healthcare Professional - Organization	PATCH /Task/{executionID}	in-progress	200 OK	- Add Task.executionPeriod.start. - Previous task status must be ready or cancelled.

Record Execution End

Business objective	Actors	Endpoint	Task status after operation	Success	Key integration notes
Finish execution, not assigned yet	- Healthcare Professional - Organization	POST /Task	completed	201 Created	Create a completed task with: -executionPeriod.start -executionPeriod.end
Finish execution, already started	- Healthcare Professional - Organization	PATCH /Task/{executionID}	completed	200 OK	- Add only Task.executionPeriod.end. - End must not be in the future. - End must not be before start.

Record Execution Interruption

Business objective	Actors	Endpoint	Task status after operation	Success	Key integration notes
Interrupt execution	Healthcare Professional	PATCH /Task/{executionID}	on-hold	200 OK	- Replace Task.status. - No informed-consent, therapeutic-relation, or exclusion checks are applied for this interruption operation.

Cancel Execution

Business objective	Actors	Endpoint	Task status after operation	Success	Key integration notes
Cancel execution	Healthcare Professional Organization	PATCH /Task/{executionID}	cancelled	200 OK	- Replace Task.status by cancelled. - The task can later be reused by the caregiver.

Manage Evaluation

Evaluate Proposal

Business objective	Actors	Endpoint	Success	Notes
Approve proposal	Healthcare Professional (Physician)	POST /ServiceRequest/{serviceRequestID}/$approve	200 OK	- Completes the proposal workflow. - Creates a valid prescription. - Assigns the caregiver who authored the proposal. - Optional clinical note must be encrypted.
Reject proposal	Healthcare Professional (Physician)	POST /ServiceRequest/{serviceRequestID}/$reject	200 OK	- Completes the proposal workflow as rejected. - Optional clinical note must be encrypted.

Evaluate Radiology Prescription

Business objective	Actors	Endpoint	Success	Notes
Accept Exam	- Healthcare Professional - Organization	PATCH /Task/{executionId}	200 OK	Replace PerformerTask.status by accepted
Substitute Exam	- Healthcare Professional - Organization	PATCH /Task/{executionId}	200 OK	- Replace PerformerTask.status by accepted - Add new exam to perform as PerformerTask.output[]
Refuse Exam	- Healthcare Professional - Organization	PATCH /Task/{referralTaskId}	200 OK	Replace PerformerTask.status by rejected