Sending and receiving correspondence


When we launched the FHIR edition of the Send documents and Receive documents components, it supported sending and receiving documents for referrals and request forms to healthcare organizations. In the meantime, our platform has developed and has started supporting sending correspondence (e.g. reports and transfer dossers) to individual practitioners or organizational units. We are happy to announce that our FHIR interface now also supports sending and receiving these documents! We have implemented this new functionality as a non breaking extension to the following components: 

  • Send documents: it’s possible now to specify additional context parameters like the document type you’d like to send and suggested recipient using a Task resource.
  • Receive documents: it’s now possible to receive documents for individual practitioners. 

This page will specify how these two components can be used to either support sending or receiving correspondence documents. 

Send correspondence documents

The default user flow for sending correspondence in ZorgDomein follows the following steps: 

  1. Log in to ZorgDomein
  2. Select document type
  3. Select the recipient
  4. Enter the patient context
  5. Compose the document
  6. Send the document

Each of these steps can be facilitated by our FHIR interface. Below we will discuss how these steps steps can be supported by a connector. 

1. Log in to ZorgDomein

To automate login to ZorgDomein, you must support the SSO to ZorgDomein component. 

2. Select document type

In the SSO-call to ZorgDomein you can specify the application context in ZorgDomein using a Task resource. As part of this context you can specify the action the user intends to perform in ZorgDomein using the Task.code attribute. To send a correspondence document like a report or a transfer dossier, choose one of the following values for Task.code.coding.value, while setting Task.code.coding.system to

  • send-document
  • send-medical-report
  • send-admission-report
  • send-progress-report
  • send-discharge-report
  • send-procedure-report
  • send-response
  • send-transfer-dossier
  • send-medical-transfer
  • send-medication-transfer
  • send-nursing-transfer
  • send-palliative-transfer

See the specification of the Launch intent code system for more details about these launch intent values. Depending on the value in Task.code, ZorgDomein will automatically select the corresponding document type, so that the user does not have to select this document type manually. 

3. Select the recipient

There are two ways in which the interface facilitates recipient selection: 

  1. For documents that are sent as a reply to a referral or request that was received previously (“terugrapportages”), the recipient will be set to the sender of that initial referral or request. You can specify the related transaction in the Task resource that is specified in the SSO token using the Task.basedOn attribute as follows: 
    • Task.basedOn.identifier.value: ZD-number of the related transaction
    • Task.basedOn.identifier.system: fixed value:
  2. For other documents you can suggest a recipient in the Task that is specified in the SSO call using the Task.owner attribute as specified here

4. Enter patient context

The patient that should be set on context in ZorgDomein (c.q. the patient to whom the document applies) can be communicated through the Task resource that is specified in the SSO token using the Task.for attribute as described here

5. Compose the document

The user composes the actual document using a form in ZorgDomein. This form consists of a set of fields. The field set is defined by a form template, which in its turn depends on the document type that the user has selected in ZorgDomein. ZorgDomein tries to prepopulate (some of) the fields in the form by requesting relevant resources at your FHIR server. This way the user does not have to copy the data from his information system to the form in ZorgDomein. See this list to see which form fields are currently supported by FHIR queries (this list may be extended in the future).

If users compose the actual document within your XIS instead of in ZorgDomein, it is possible to supply a pregenerated document to ZorgDomein. Read more about this here

6. Send the document

Besides the fact that ZorgDomein will deliver the document to the intended recipient, a copy of the document will be sent to the XIS of the sender. This document will be delivered as a FHIR Document, hence ZorgDomein will issue a HTTP POST request to your Bundle endpoint. Read this paragraph for more details.

Receive correspondence documents

The most important change for the Receive documents component is that correspondence documents can be sent to individual practitioners (referrals and healthcare requests are always sent to organizational units, not to individuals). When a document is sent to an individual practitioner, ZorgDomein will try to deliver the document for the receiving practitioner in the XIS of this practitioner. This implies that ZorgDomein will push a FHIR Document to the XIS of the recipient using a HTTP POST. See the specifications of FHIR Documents details about these documents. See this paragraph for details about delivering documents to individual practitioners.

Next to that we have introduced a few new document types. See the complete list of document types here


As mentioned above, we have implemented the functionality of sending and receiving correspondence as a non breaking extension to the Send documents and Receive documents components. This implies that you have to implement these components if you intend to implement the functionality of sending and receiving correspondence in your connector. As part of the release process we will validate your connector based on the validation criteria for these components.