Developers introduction

Introduction FHIR

For this introduction, a certain level of FHIR know-how is assumed. If you are new to FHIR, it is highly recommended to first read the FHIR introduction for developers.

Interaction with ZorgDomein

XIS Server (sending)
XIS client (sending)
XIS Server (receiving)

A more detailed overview of flows is available. That overview includes the message types used for every interaction with links to the specifications of those message types.

The Request module

The Request module covers interactions 1 to 3 from the diagram above. 

Using the Request module users of connected organizations can compose documents on ZorgDomein and send these documents to healthcare providers. Examples of documents that can be composed in and sent from ZorgDomein include referral letters and diagnostics requests.

The Request module consists of 3 parts: 


The single sign-on (SSO) functionality is implemented by utilizing JSON Web Token (JWTs) . JWTs are a simple and secure means to exchange a dataset between two systems. For all commonly used development platforms, libraries are available to generate and validate JWTs.

Every SSO token must include both an organization identifier and a user identifier. The organization identifier should be recognized in ZorgDomein (see: Auto-activation). When a user identifier that is not recognized in ZorgDomein is included, the user will be prompted to create a ZorgDomein account by following a registration process. Once the account has been created, the user may sign on and the user identifier will be linked to the ZorgDomein account. From there on out, the user is able to use the SSO without manually having to sign on to ZorgDomein.

The last part of the token is a signature. This signature is created by a private key from the XIS, which ZorgDomein validates with a corresponding public key. That way, only users from trusted XISes are able to gain access to ZorgDomein.

If a patient id is included in the token, a FHIR read (see: Retrieving data) will be executed after signing on to retrieve the Patient resource.

As a security measure, every token will only be accepted once and is valid only up until five minutes after its creation.

Retrieving data

To support users in composing documents, ZorgDomein retrieves information from the XIS of the care requester. To this end, FHIR reads and FHIR searches are used. For every type of resource, a separate endpoint should be made available by the XIS. For example, patient information would be retrieved from the Patient endpoint ( and medication information would be retrieved from the MedicationStatement endpoint (

A mutual TLS connection is used for retrieving the information. In addition, ZorgDomein supplies every HTTP call with a JWT. The JWT contains information about on which user’s behalf ZorgDomein executes the call. This is achieved by supplying the user identifier that was exchanged in the SSO. This information enables a XIS to validate the user’s authorization to retrieve specific information.

FHIR reads

A FHIR read is used to request a resource pertaining to a specific technical id. The FHIR read is executed by means of an HTTP GET call. 

FHIR searches

A FHIR search is used to request resources on the basis of various parameters. The FHIR read is executed by means of an HTTP GET call which contains a query-string. 

Feedback copy 

At the time ZorgDomein sends a document to a receiving party, simultaneously a copy of that document is sent back to the XIS of the sender. This means that the care requester has to be able to receive documents as well. In order to achieve this, the Request module follows the same implementation of receiving documents as the Receive module.

The Receive module

The Receive module covers interaction 4 from the diagram above

The Receive module enables users to receive documents such as referral letters, diagnostics requests, and reports. ZorgDomein transfers the information by means of FHIR documents.

FHIR documents

A FHIR document is a Bundle resource in which various resources are incorporated integrally. The first resource of a FHIR document is a Composition resource. The Composition contains the text of the document, split into different sections and references to resources that support the text. Two examples of references are one that refers to the Patient resource, which contains administrative information of the patient, and a reference that refers to the Practitioner resource, which contains information about the sender. FHIR documents sent by ZorgDomein also always contain a copy of the document in the pdf format. More information about documents can be found in this implementation guide.

Receiving documents

ZorgDomein sends documents by means of an HTTP POST call to the Bundle endpoint (e.g. of the receiving party. This means a push from ZorgDomein to the receiving party. A condition for this is that a mutually authenticated TLS connection can be deployed between ZorgDomein and the endpoint.

Delivering documents

Every document contains an Organization resource and potentially a Practioner resource with information about the receiver. This way, the document can be delivered to the right person or organization. This enables the XIS supplier to serve a large group of users with a single endpoint. In order to know where to deliver a document, every document contains a destination element. The document also contains an author element and a receiver element. In the copy of the document that is used for feedback (see: Feedback copy), the author is the same as the destination. In all other cases, the receiver is the same as the destination.


To enable testing the functionality of receiving documents, ZorgDomein has made a test tool available. The tool will let you compose a document and order ZorgDomein to send the document to an endpoint. This way, you can swiftly test if your system can process ZorgDomein documents. This tool does not require a mutually authenticated TLS connection.

The specifications of FHIR documents that are sent by ZorgDomein can be found on the profile page of ZD Document.

  • Deze informatie is alleen beschikbaar in het Engels.
  • The information on this page applies to ZorgDomein Integrator FHIR Edition.