Ga naar hoofdinhoud

Condolidated API for health information search and retrieval

We present an API for localizing and fetching information in different XIS systems - the EPD systems of healthcare providers that contain information about their patients. We call this a consolidated API.

The consolidated API intends to unify the search/localize and retrieve interfaces of different health information exchange (HIE) systems - such as Nuts, LSP, NVI/LMR, XDS and push authorization - for locating and obtaining patient data.

Our goal is to create an open API specification and an open source framework that is can be used to integrate different implementations of generic functions, in particular auhentication and localization, in a similar way. This should allow for straightforward integration of existing and novel HIE systems in different XIS systems.

The context is the PoC project initiated by the ministry of health (VWS) over 2025/2026 (see https://www.datavoorgezondheid.nl/.../2025/04/16/start-europese-aanbesteding-voor-pocs...generieke-functies and https://www.datavoorgezondheid.nl/generieke-functies ).

This API will be developed in an open process that leads to an open specification and open (example) source code. The code will initially be published through Decozo.org.

TLDR; For a quick walkthrough of using the consolidated API in a straightforward way, see the section Examples.

Introduction​

The consolidated API is a generalization of an API provided by a component originally designed by Whitebox Systems for looking up push authorizations and using these to request information. This component, the 'Dienstverlener push autorisatie recipient (DVPA-r)' uses a local index that contains push authorization URLs and [?] that can be used to search push authorizations.

Other systems use a different approach. In XDS and the LSP, localization information is stored in a centralized index. The Dutch ministry of health has taken steps to implement a distributed index where a centralized national reference index (NVI) refers to decentralized local metadata repositories (LMR) provided by healthcare providers (XISes) to find more detailed information about patients https://github.com/minvws/generiekefuncties-lokalisatie/issues. Other approaches exist with varying degrees of centralization and with differing security architectures, e.g., [?]

The consolidated API aims to provide an open source framework to allows XIS'es to interact with different Health Information Exchange (HIE) systems to make it easier to integrate differing approaches for localization and information retrieval.

Using a convenient, small set of high-level abstractions, the consolidated API's goal is that XIS'es have to worry less about differences between HIE's and changing technical specifications. This facilitates faster improvement of existing HIE systems as well as limiting barriers to adoption for novel systems, leading to increased levels of standardization of HIE systems in the long haul.

Approach​

Seen from the XIS that has to find and obtain patient records, differences between HIE systems manifest themselfs mainly in authentication mechanisms. The arguments to search calls are largely identical, and the method for retrieving (fetching) information differ per HIE system, but are relatively easy to hide as such methods use comparable (although not identical) authentication mechanisms and return largely [?] information.

The proposed approach is supported by the following factors:

  • NEN norms for Generic Functions (GF's) are being developed, which provide clarity on what search fields must be supported for localization (NEN7519, published), and on the granularity of and mechanisms for authentication (NEN ontwerp-norm 7518) and authorization (NEN7520, under development).
  • Standardization of the content and representation / encoding of patient health information has progressed significantly over recent years, so that for most health processes in the Netherlands, standardized data sets (also called "information standards") ar available. This means that irrespective of the HIE system used, parties can retrieve the information the same way, at least for sectoral health information exchange.
  • In situations where information standards are not supported by all communicating parties, fall-backs exist. Web standards have progressed such that it is often possible to revert to data encoding standards common on the Web - e.g., standard to exchange renderings of radiological images using standard image encoding formats in DICOM-web - when regular health exchange does not work.
  • The Web also gave birth to various authentication and authorization standards such as OautH 2.0 and OpenID/connect as well as the concept of verifyable credentials that can be applied in various health information exchange systems.

Authorization mechanisms differ per HIE but similarities exist. In most cases in Dutch healthcare, an authentication token exists has that must be signed and shipped to the source along with the request. In some cases, the client may have to present such a token to an (OpenID/connect-based) authorization server to [?] and exchange it for an access token that can be used to fetch a resource. Tokens come in different forms such as SAML or JWT, or taken the form of a verifiable presentation. Not all differences between those tokens and formats can be hidden, but most of them can.

In all, we see similarities between HIE systems that are currently in use. production or under development. When different HIE technologies can be used side by side, availability of patient information can increase, more options for exchanging health information can be provided to patients an doctors, and innovation increazses. By providing a consolidated interface for the most important functions of HIE systems: searching and retrieving data, we believe we are placing a step in the right direction.

Positioning the consolidated API and its supporting middleware​

The following figure shows the location of the consolidated API and how it interacts with different HIE infrastructure components.

Consoloc Design

In above figure, you see a XIS system of a healthcare provider, which is connected to the consilidated API. Internally, the API is part of a modular framework consisting of open-source components that connect to different HIE components that expose search/localization functionality. For example:

  • A connection to the LSP infrastructure
  • A connection to the NVI/LMR infrastructure
  • A connection to a Nuts node that connects to the NVI and LMR instances als an alternative to a direct connection to the NVI/LMR infrastructure (see above).
  • Nuts may also provide additional localization primitives, for example based on a FHIR task containing a Careteam resource (under develppment)
  • A Twiin node or "knooppunt" that interfaces with XDS infrastructure components to find resources made available using IHE-XDS mechanisms
  • A connection to a push authorization module (DVPA-r) which contains locally stored push authorization URLs and metadata

The consolidated API provides mechanisms for searching information (localization) and for retrieving localized data, hiding differences between the API's of different HIE infrastructures from the XIS system using it.

Besides the primiteve search and retrieve calls, the consolidated API provides prepare methods to help XIS'es in implementing the required steps for authentication/authorization to be able to invoke these calls.

API Specification​

This spec is based on ideas and concepts from the push authorization project, and on ideas and concepts that originate from the NEN751x series of norms for general functions (GFs). The search/response struct that is input and output of the search call, closely matches the information model of the localization structure specified in the NEN norm NEN 7519 Lokalisatie (2026).

This spec is intended to be high-level and thus is not intended as an implementation guide in this form. An example will be provided as a practical translation of this API that may be used as a starting point for PoC implementations.

The essential calls are:

  • prepare-search
  • search
  • prepare-retrieve
  • retrieve

Key in understanding the consolidated API is to understand the prepare calls. The consolidated API and its supporting middleware implementation know how the underlying HIE systems work and what kind of token is required when invoking functionality -- tokens which generally differ for seach and retrieve calls. Further, the middleware may also have other things to manage, such as making preparatory calls on an OAuth server to obtain an access token and request URL if a resource server makes use of OAuth; or to fetch a new PA-url from the source in case of push authorization. The API hides such differences by implementing those inside the middleware.

Interaction pattern​

The interaction pattern for a XIS that uses the consolidated API is:

1. [API] prepare-search => token template

--> External component: complete and sign token (e.g., using ZorgID or wallet)

2. [API] search => search results

Note: between steps 2 and 3 some time may pass, e.g., if a patent is first entered by assistent, search can take place. Patient arrives in practice an hour later, and seen by doctor who selects and retrieves records after another half-hour.

3. [API] prepare-retrieve using selected search results => template token

--> External component: complete and sign token (e.g., using ZorgID or wallet)

4. [API] retrieve for selected search results => returns data

We will start with describing the search call and the perparatory prepare-search and its in and out arguments.

Subsequently we will describe the optional prepare-retrieve and retrieve calls, which can be used for requesting data from localized resources.

Structs and definitions​

Note: this specification is work in progress. Types including data types in structs (e.g., strings) are indicative and presented as examples only.

The below structs may be used to search for patient records (Localizable data sets (LDS's)). Whether the information (metadata) in these struct is available for search, depends on whether this information was included when disclosing the localization metadata.

Below searchable metadata are based on the LDS Metadata structure described in NEN7519.

Patient information​

The below enums and structs are basic types used as in parameters by the prepare-search, prepare-retrieve and search and retrieve calls.

Only PatientID, DisclosingParty.healthcareProvider and LDS.Type are mandatory for a disclosing party to publish, if NEN7519 compliant. Endpoint information is (obviously) also mandatory to disclose, but this is not a search parameter.

enum PatientIDType {      // patientID types, TBD
    BSN, pseudonym, ...
}

struct PatientMeta {     
    string id,
    PatientIDType idType,
    string name,
    string birthdate,
    string street,
    string housenumber,
    string postalcode,
    string province,
    string city
    string gender           // M,F,O,U (other, unknown)
}

LDS metadata​

A localizable dataset (LDS) may be described using the metadata described below.

LDS metadata describes properties of the localizable dataset.

The LDS metadata fields are defined in the NEN7519 Localization norm.

struct LDS { 
   uuid id, 
   LDSType type,             // Nictiz-defined, may be encoded as string
   LDSSubtype subtype,       // Nictiz-defined, may be encoded as string
   LDSFormat format,         // Nictiz-defined, may be encoded as string
   dateString creationDate,
   dateString validUntil,
}

DisclosingParty​

DisclosingParty describes the organization and (optionally) person that published (disclosed) the LDS

struct DisclosingParty { 
    string healthcareProviderName,
    string healthcareProviderId,         // e.g., URA
    ProviderType healthcareProviderType  // Nictiz-defined list of types (zorgaanbiedertypes)
    string personName,
    string personID,                     // e.g., UZI number
    string persionType                   // Nictiz list, e.g, specialization

CareData​

CareData is information about a specific medical episode or treatment, which is useful to associate patient records (LDS'es) from different source systems that are related to each other. CareData can also contain information about the specialist responsible for treatment. 

struct CareData { 
    int trajectoryID                     // Trajectory number, provider-assigned
    string trajectoryBundle              // unique, encoded bundle identifier
    string professionalName,
    string professionalID,               // e.g., UZI number
    string professionalType              // Nictiz list, e.g, specialization      
}

Endpoint information​

Endpoint information may be returned by a search call, if the argument details is specified (see below). Endpoint information is, in principle, only needed by the consolidated API for invoking a retrieve call. However, the caller may obtain this information if it wants to connect to an endpoint directly.

enum EndpointType { direct, indirect }    // URL or resolve via address book

struct Endpoint { 
    string address,       // URA, IP-adress/port, URL
    EndpointType type,
    string resolver,      // address or name of resolver (e.g., ZAB)
    datestring validUntil // renew endpoint address by renew search to make sure it still exist
}

A localization infrastructure may be:

  • a centralized index, such as the LSP's VWI or an XDS registry;
  • a distributed version thereof such as the NVI/LMR based solution;
  • an index that is part of a local node in which localization information was registered directly, as for example in push authorization.

Typically, a document type (LDS.type) will be specified to look for a particular type of resource (e.g., a medication record). DisclosingParty.ProviderType may be used to look for a resource of a particular provider type (e.g., a pharmacists).

If a specific metadata field is specified in the search, the query results must match these fields.

Whether or not resources (can) match the parameters/members that were filled in in the in arguments, depends on what information was published though the localization infrastructure. Examples may involve enabling searching for documents that are related to a particular treatment trajectory, or documents with particular subtypes (e.g., radiological images of a specific bodypart), or to create a timeline to cater to the needs of a specific health professionals or use cases (see NEN7519). Such examples are out of scope for this document.

Token handling​

In practice, Dutch HIE infrastructure and source systems that receive retrieve requests use signed tokens to authenticate [?]. Such tokens are signed by the health professional for authorization and auditability (non-repudiation) purposes.

Tokens come in different forms, but essentially have the same function. Tokens are used fo authenticate a request, as it passes thorough different layers or components (e.g., communication servers) of a system on the way to an endpoint where information is to be retrieved. Being signed, the token ensures that the request is not modifyable without detection.

Tokens have a type - indicating content and representation/encoding standard - that can differs per HIE infrastructure and sometimes per operation. For example, the LSP uses a request token specified in SAML that contains the patient's BSN, an interaction specifier, and a signing date. Other infrastructures accept JSON-Web tokens or verifiable presentations containing various attributes that are used for authentication and authorization of requests.

The semantics of tokens for invoking resource endpoints differ from tokens intended for localization. In particular, a token used for retrieving data from a resource is typically specific to that request to avoid replay, whereas a localization query by definition cannot specify a specific resource as this resource is not located yet.

The consolidated API aims to provide XIS'es with mechanisms that hide much of the abovementioned differences between HIE tokens (and other preparatory steps) from the XIS implementer [?].

Below, we first describe general properties of tokens from the perspective of a XIS using the consolidated API. Next, we describe examples of using search tokens. At the end of this document, we describe request tokens.

Authentication tokens​

Tokens are HIE-specific and can be prepared by the prepare-search and prepare-retrieve calls.Tokens have the following format: 

enum TokenType {         
    SAML-LSP, JWT-PA, JWT-VP, ...
} 

struct Token { 
   TokenType type,     // e.g., JWT-PA or SAML-LSP token
   string token
} 

enum HieType {           // health exchange infrastructure (HIE) types
    LSP, PA, Nuts, NVI-LMR, XDS, ...
} 

struct HieToken { 
   HieType hie,
   Token token,        // self-contained token, including signature and key certificate
}

An authentication token is typically signed using a private key of the person invoking the search or retrieve request. A signed token will typically be accompanied by a certificate that binds the public key to the name or ID (e.g., UZI or Dezi-ID) of the caller, and is signed/issued by a trusted party, i.e., a certificate authority or an issuer. In modern tokens, the signature and certificates embeded in the token. Such a standardized token with a type indicating the format is stored in HieToken.token.

The prepare-search/retrieve calls prepare and return a template token that must be completed by the XIS and signed. Completion implies insertion of specific, HIE-defined attributes in the template token that the consolidated API cannot fill in, such as the signer's keyid a timestamp or an expiry (retrieving a record may take place a while after searching and locating the patient's records).

The TemplateToken is mostly filled in by the consolidated API, with an indication of what needs to be filled in by the XIS, and returned as part of the AuthToken structure described below. 

struct AuthToken {     
   HieType type,               // HIE specific, LSP, PA, Nuts, ...
   TokenTemplate token,        // token template returned by prepare-* calls
   PatientID patientId,        // contains patientID if patient-bound token, else empty
   int expiresIn               // seconds after start/signing (validity)
} 
 
struct Path {
   Syntax syntax,              // JSON (pointer), SAML/XML (XPath)
   string value
} 

struct TokenPlaceholder { 
   string name                 // placeholder name e.g., "patientID", "iat" ..
   Path path                   // where to place value inF 'path'
} 

struct TokenTemplate {         // TODO determine required datastructure fields
   TokenType type,             // e.g., JWT-PA or SAML-LSP token
   string tokentemplate,       // self-contained token encoded as string
   TokenPlaceholder[] attribute-placeholders
}

The consolidated API fills template-tokens based on what information it has available and what is required for a specific HIE, but it cannot fill in every field. Examples are a specific validity period ([?]) that is relative to the moment of signing and thus must be included in the token at that time, or the keyid of the signer.

The AuthToken struct contains the template token and a list of attributes that must be completed by the XIS. The TokenPlaceholder struct contains pointers to the attributes that need to be filled by the XIS using the Path substructure.

The AuthToken struct contains sufficient information to check and prepare the token for signing.

(In case of a retrieve call, the consolicated API can pre-fill in most attributes based on information returned by an earlier search call; this information is stored internally and referred to by the resultId, see description of the retrieve call in the Methods section above).

Note on token standardization​

Different infrastructures (such as XDS, LSP, or the NVI/LMR infrastructure) require different token formats. The problem is not so much the technical differences but that some tokens differ in semantics. For example, some HIEs require single-use tokens for search that specify the patent, others support tokens for search that can be used for multiple patients over a period of time.

Given the semantic differences between HIE tokens, it is clear that the consolidated API cannot reduce complexity for all aspects of managing different HIE's to locate and retrieve information. In some cases, tokens may have to be completed and signed for each search call, in other cases not. The XIS has to manage these differences.

There is clearly an argument to make that all HIE infrastructure in the Netherlands or beyond agree upon and accept a single 'consolidated token' -- or at least a consolidated token semantics -- so that tokens are equivalent (even if represented differently) between HIEs. This not only helps achieving a consistent, simple use of a consolidated API for token preparation and signing. Agreement on token content also helps to align and standardize authorization policies.

Token management using the consolidated API​

The differences in token semantics are most noticeable with the search call.

A simple solution for a XIS to avoid managing tokens differently for each HIE, is to simply do a prepare-search call always, and complete and sign a new token for every search call, irrespective of the type of HIE. This way, the interaction with the consolidated API is consistent, yielding a simple programming model even though this may come at [?] cost.

For the retrieve call, the semantic differences between tokens are small and manageable. Our interpretation of EU regulations, is that these demand that retrieve calls must be patient-bound, short-lived, and signed by professionals -- although the aspect of who may sign a token relates to authorization policies and does not impact the consolidated API directly. Tokens for the retrieve call should thus be assumed to have the mentioned semantics, requiring token preparation and signing for each retrieve call, irrespective of the HIE. We believe that HIE tokens will converge to a this semantics due to EU legal requirements (NEN7520 and NEN7518, in development).

Methods​

The prepare-search call prepares a set of HIE-specific tokens that must be completed and signed to invoke the search call. The mechanism for preparing and completing tokens is described above.

method HIE-list (
) => out: HieType[] types

method prepare-search (
     in: HieType[] types, 
     in: PatientID patientID 
} => out: AuthToken[] tokens

prepare-search accepts one or more HIE types as input and generates for each type a token that is returned as a list of AuthTokens.

The call takes one HieType as input or a list, if multiple (or all) supported are to be searched.

prepare-search also takes a patientID. This ID may not strictly be required for all HIE infrastructure's search calls, but it is taken so that the API is consitent (see also the Notes above).

Often HIE-specific tokens are single-use and require a PatientID to be part of a token (see 'Handling tokens', above). Therefore PatientID is part of the prepare-search call. If this field is not needed, the consolidated API ignores the field.

The search call has the following signature: 

method search (
     in: HieToken[] tokenset,
     in: datestring startDate,
     in: datestring endDate, 
     in: PatientMeta patient,     // metadata to search on, patientID is the only mandatory field
     in: LDS ldsMeta,             // any metadata filled in must match for results.
     in: DisclosingParty discloser,
     in: CareData caregiver
     in: bool details (optional)
) => out: SearchResult[] results

The XIS knows what LDS types it needs in a particular workflow, and what LDS formats it can accept, so it can fill those properties in in ldsMeta. It can however also do a broader search, so it can present up a 'timeline' of available data sources (LDS'es) to a user even if the XIS is not able to read in all those sources electronically (a fallback may be to view such sources in a web browser, see section Approach).

The search call takes a set of tokens as an argument, one for each HIE to be queried/searched. This makes it possible for a single search call to return results (LDS'es) that are accessible through different HIE's.

The search call returns a set of results as a set of SearchResult structs: 

struct SearchResult {
   int resultId,
   HieType type,
   PatientMeta patient,
   LDS ldsMeta,
   DisclosingParty discloser,
   CareData caregiver,
   Endpoint endpoint
}

For SearchResult, fields are returned as they are made available by the party who disclosed the localization metadata.

Each search result describes a unique LDS, in a specific format ldsMeta.format (LDS.format) that can be retrieved. The format is usually fixed, with the LDS represented in a specific "message format". Since the retrieve call takes a resultId as an argument, a XIS always retrieves one LDS in the format indicated in ldsMeta.format.

ldsMeta.type (LDS.type) indicates what patient information is in the LDS, for example a GP professional summary conforming to NHG specifications (NHG-PS) or an AMO containing medication information. An LDS type may pre presented in different format, for example in HL7v3 or FHIR format.

SearchResult.resultId is an ID generated by the consolidated API that acts as a reference to a result for subsequent API calls. It is available for 24 hours after generation.

[?], `LDS.Format`, `DisclosingParty` and `Endpoint` are mandatory for NEN7519-compliant disclosed LDS-metadata, and SHOULD be present in `SearchResult`. Other LDS-metadata is optional.

Prepare-retrieve​

The prepare-retrieve generates a template token to use (sign) for a given result of a search call, indicated by SearchResult.resultId.

The consolidated API knows what information is needed to create an AuthToken based on the search results referred to by resultId. This includes PatientID, LDSType and Endpoint information.

What of this information is required in a token is determined by the HIE, and passed back in AuthToken, as explained above.

method prepare-retrieve (         // prepare token for retrieve / GET data
     in: int resultId                 
) => out: AuthToken token

Note: depending on the HIE, the prepare-retrieve call may do more than just prepare a token. For example, based on the information received by search (referred to by resultId), the consolidated API can look up the address of the authorization server to which the token must be presented (to exchange it for an access token as required by a FHIR resource, see below), to ensure it is available for a subsequent retrieve call. The mechanism for exchanging a token for an access token would be implemented as part of the retrieve call.

Retrieve​

The retrieve call returns a patient record in a predetermined format -- subject to an authorization policy.

The XIS knows what LDS types and LDS formats it accepts. From the search results, the XIS can select an LDS in an LDS-format (i.e., encoding of the LDS, for example "HL7v3" or "FHIR") that it can read, parse and store.

token is the token prepared by prepare-retrieve and signed by the caller. resultId indicates what record (LDS) to fetch. Arguments are optional (see below).

The result of retrieve is the content of the LDS as returned by the source system, in the requested format. 

method retrieve (
     in: HieToken token,               
     in: int resultId,
     in: string arguments       // may contain e.g., request parameters to pass to FHIR
) => out: <patient record>      // raw content / returned data

The retrieve call will return a LDS in a predefined format (LDS.format).

LDS format FHIR is a somewhat special case. Although a FHIR resource can be presented as a 'message' containing a bundle or collection of ZIBs, a FHIR resource may also be represented by a FHIR resource (endpoint) that can be queried directly. For this situation, the consolidated API allows for the XIS to place query parameters in the arguments field of the retrieve call, which will be passed (proxied) to the FHIR server if the XIS wants to retrieve only specific parts of the resource. The consolidated API can be implemented such that the consolidated API URL + resultId act as a base URL to proxy FHIR queries to the resource server transparantly, maintaining consistency with the way that FHIR handles requests (see example 4B).

A note on using OAuth and FHIR in the consolidated API middleware​

Current FHIR implementations separate the authentication and authorization steps from invocation. A FHIR resource server accepts only OAuth access tokens that are issued by a (trusted) authorization server associated with the resource server. Authentication (in this case using tokens) takes place toward the authorization server, which returns an access token. Using this token, the resource server consults the authorization server to determine what scope belongs to it. This way, OAuth separates the authorization mechanism from the mechanism used to invoke the resource server.

The consolidated API hides the step of obtaining and using an access token from the XIS in the prepare-request and request calls, see notes in the section on the retrieve method.

An example of how it may work for Nuts is described here. Authentication towards the authorization server requires the use of a verifyable presentation (VP) signed using a wallet. The steps to create such a VP as a "token template" can be taken in the prepare-retrieve method. The VP created by prepare-retrieve calls should be completed and signed by the XIS using a wallet -- this is an external process, as indicated in the section API specification.

The retrieve call presents the signed VP to the OAuth Authorization Server, to exchange it for an access-token with which the FHIR resource server can be invoked to obtain the FHIR bundle, or the results returned after passing the arguments to the resource server.

Appendix: NEN7519 Localization information structure​

Below describes LDS metadata as defined in the NEN7519 norm, for reference purposes.

PatientMeta
PatientMeta.ID                    // The patient's BSN, pseudonym or other (global) ID
PatientMeta.IDtype                // Type of ID: pseudonym, BSN, other..
PatientMeta.Name                  // Full name (givenname, spouse, initials, ..?)
PatientMeta.Birthdate             // Date of birth (in yyyy-mm-dd format)
PatientMeta.Street                // The patient's streetname
PatientMeta.HouseNumber           // The patient's housenumber
PatientMeta.PostalCode            // postal code (in 1234AA format)
PatientMeta.ProvinceState         // Province or State name, if applicable
PatientMeta.City                  // City / placename
PatientMeta.Gender                // Patient's gender (M/F/O/U) [o=other, u=unknown]

// Notes on LDS
LDS stands for 'localizable data set'. It is generally comparable to the notion of a DocumentType.

LDS.ID is a DisclosingParty-assigned identifier for a specific localizable data set (LDS). This ID may not always exist, as only
NEN7519-compliant DisclosingParties provide it.

LDS.Type is the type of the Localizable Data Set -- this type describes the data set
that is made available. Examples are the NHG Professional Summary (NHG-PS), a medication record (AMO), or 
Radiology-images or -reports. These types are either well-known strings or SNOMED codes (see NEN7519).
LDS.Format describes the specific technical 'message format' of the resource- e.g., DICOM, FHIR, HL7v3.
A party searching for data may request LDSType or LDSFormat or a combination thereof. 
NB: LDS.Format is part of the Endpoint structure in NEN7517. It is placed here as it logically 
belongs to the LDS, even though it describes a technical format of a LDSType, associated with 
an endpoint.

LDS
LDS.ID                        // DisclosingParty-assigned unique ID (uuid), if available. Matches 7519 LDS-ID
LDS.Creation                  // When was the LDS resource opened for requesting
LDS.ValidUntil                // Intended expiry. Informative, use as a hint.
LDS.Type                      // Type of a patient record
LDS.Format                    // Technical format of patient record (LDS.Type): HL7v3, DICOM, FHIR..
LDS.Subtype                   // (List of) more specific information, e.g., bodypart in DICOM (SNOMED code)

// Note on DisclosingParty
DisclosingParty (who disclosed the LDS and published the metadata) may not be the same as the phycisian 
(professional) or ward (afdeling/specialisme) responsible for treatment. 
Often only the healthcare provider (organization that disclosed the LDS) will be
made available. If a professional (person) is included in DisclosingParty.Professional, this is included
for auditability; this person may not have anything to do with treatment of the patient (see Caredata).

DisclosingParty
DisclosingParty.Provider         // Healthcare organization
DisclosingParty.ProviderType     // specialism
DisclosingParty.Person           // professional or supporting staff
DisclosingParty.ProfessionalType // specialism, if applicable

// Note on CareData:
CareData is an optional field, that may be extensible for certain usecases. CareData may not be provided by 
DisclosingParty as it can concern detailed information related to treatment.This also holds for information 
about the treating physician, Professional. Note that DisclosingParty often describes (only) the 
organization, which can have broader granularity than Ward or Professional.Type).
 
In its basic form as described here, CareData may be most relevant for grouping resources from different 
sources related to particular episodes of care, through the CareData.TrajectoryBundle field.

CareData                       // Optional information to select / search treatment information (if avail)
CareData.Trajectory            // Locally assigned identifier for a given problem; may transfer providers.
CareData.TrajectoryBundle      // Pre-assigned code for a specific cross-provider treatment type
CareData.Professional          // Responsible healthcare professional (person)
CareData.Professional.Name     // Name optional
CareData.Professional.UID      // In NL: UZI, mandatory if available
CareData.Professional.Type     // In NL: BIG/Role-code
CareData.Professional.Ward     // Type / specialism of treatment group ('afdeling')

// Note on endpoint information
Edpoint information is normally not returned through LocalizationOut, as it is typically not used to
select relevant information (also, because the consolidated API and middlware intend to hide implementation
details from the user/XIS). The parameter "Details" in the search call should be set to True to expose this
information. (Note: NEN7519 places LDSFormat here, but we place it with the LDS fields, see above. The API
middlware may used this field to query the resolver for a particular message/data type.

Endpoint                       // How to contact service to obtain/query LDS
Endpoint.Address               // URA, IP-address/port, URL
Endpoint.Type                  // Direct or indirect address
Enpoint.Resolver               // 'Addressbook' or empty if type=direct
Endpoint.ValidUntil            // Provider-guaranteed availability of endpoint (as long as available)

Example​

Example: a simple search and retrieve flow​

Legend The notation ... indicates abbreviated or omitted content that is not relevant for the example or needs further specification.

This page describes a basic, minimal flow for searching and retrieving patient-related documents across one or more HIE systems. Such a flow represent a common case, where a XIS tries to locate and retrieve any record of a specific patient, of a specific type that can be processed by the XIS.

The example presents a simple flow that follows on the outline presented in the high-level consolidated API specification

The flow consists of four steps:

  1. Prepare a search
  2. Execute the search
  3. Prepare document retrieval
  4. Retrieve the document

The examples below assume the following contextual metadata:

patientId.patientId = 123443210
lds.type = NHG-PS
lds.format = HL7v3

Initializes a search request and returns authorization tokens (or token templates) for each requested HIE system.

These tokens are to be completed and signed by the end user before the actual search is executed.

Endpoint​

POST /v1/search-prepare

Request [?]​

POST /v1/search-prepare
Content-Type: application/json
{
  "hieTypes": ["LSP", "Nuts", "PA"],
  "patientId": {
    "type": "BSN",
    "id": "999999999"
  }
}

Response [?]​

200 OK


{
  "tokens": {
    "PA": null,
    "LSP": {
      "hieType": "LSP",
      "expiresIn": 3600,
      "patientId": {
         "idType": "BSN",
         "id": "999999999"
      },
      "token": {
         "type": "lsp-saml-assertion",
         "template": "<?xml version=\"1.0\" encoding=\"UTF-8\"?><saml2:Assertion xmlns:saml2=\"urn:oasis:names:tc:SAML:2.0:assertion...",
         "placeholders": [...]
      }
    },
    "Nuts": {
      "hieType": "Nuts",
      "expiresIn": 3600,
      "patientId": {
         "idType": "BSN",
         "id": "999999999"
      },
      "token": {
         "type": "nuts-vp-jwt",
         "template": "{\"header\": {...",
         "placeholders": [...]
      }
    }
  }
}

For each token in the response, the XIS must fill in some details using the placeholder strings in the prepared templateToken

Note: A value of null indicates that no token is required for that HIE system. This is the case for the PA backend, which is a local component that can be invoked directly by the XIS/consolidated API middleware.

Executes a search using previously acquired tokens, if applicable.

Endpoint​

POST /v1/search

Request [?]​

POST /v1/search
Content-Type: application/json
{
  "tokenSet": [
    {
      "hieType": "PA",
      "token": null
    },
    {
      "hieType": "LSP",
      "token": "..."
    }, 
    {
      "hieType": "Nuts",
      "token": "..."
    }, 
  ],
  "ldsMeta": {
    "type": "NHG-PS",
    "format": "HL7v3"
  },
  "patient": {
    "idType": "BSN",
    "id": "999999999"
  }
}

Response [?]​

200 OK

{
  "results": [
    {
      "id": "3f9f0020-1443-4c2f-abc2-d3e70ff08e6a",
      "hieType": "PA",
      "patient": {
        "idType": "BSN",
        "id": "999999999",
        ...
      },
      ...
    },
    ...
  ]
}

3. Prepare document retrieval​

Prepares a document retrieval call by returning a token template required to retrieve the document associated with a selected search result.

Endpoint​

POST /v1/retrieve-prepare

Request [?]​

POST /v1/retrieve-prepare
Content-Type: application/json
{
  "resultId": "3f9f0020-1443-4c2f-abc2-d3e70ff08e6a"
}

Response [?]​

200 OK

{
  "token": {
    "hieType": "PA",
    "expiresIn": 3600,
    "patientId": {
      "idType": "BSN",
      "id": "999999999"
    },
    "token": {
      "type": "wbx-jwt",
      "template": "{\"header\": {\"alg\": \"ES256\",\"x5c\": \"__PLACEHOLDER__\",\"typ\": \"JWT\"},\"payload\": {\"timestamp\": \"__PLACEHOLDER__\", ... }}",
      "placeholders": [
        {
          "name": "x5c",
          "path": {
            "syntax": "json-pointer",
            "value": "/header/x5c"
          }
        },
        {
          "name": "timestamp",
          "path": {
            "syntax": "json-pointer",
            "value": "/payload/timestamp"
          }
        },
        ...
      ]
    }
  }
}

4. Document retrieval​

Fetches a document using a previously prepared and signed token.
This section describes two proposed variants of the retrieval method, which may be consolidated or refined in later iterations.

4a. Document retrieval via POST (token in body)​

In this variant the client submits the retrieval token in the request body together with the selected resultId and optional backend specific arguments.

Endpoint​

POST /v1/retrieve

Request [?]​

Example Request​

POST /v1/retrieve
Content-Type: application/json
{
  "resultId": "3f9f0020-1443-4c2f-abc2-d3e70ff08e6a",
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXV..."
}

4b. Document retrieval via GET (token in header, resultId in path, backend arguments via path and query)​

In this variant, the token is transported in a request header, the resultId is part of the resource path, and backend-specific parameters (via additional path segments and query parameters) are passed through unchanged to the underlying backend system.

Endpoint​

GET /v1/retrieve/{resultId}/{*arguments}

The {*arguments} path segment represents a backend-specific sub-path and any query parameters.
Its structure and supported parameters depend on the selected backend and are not interpreted by this API.

Request [?]​

Example request​

GET /v1/retrieve/3f9f0020-1443-4c2f-abc2-d3e70ff08e6a/proxied/path?and-query=some-value
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXV...

Response (applies to both 4a and 4b)​

200 OK

Returns the document associated with the search result.

HTTP/1.1 200 OK
Date: Tue, 28 Jan 2026 14:32:10 GMT
Server: ExampleServer/1.0
Content-Type: application/hl7-v3+xml
Content-Length: 123456
Cache-Control: no-cache
Connection: close

...

Example: a consolidated API middleware using a Nuts authentication flow

This example describes how the Consolidated API can operate within the context of the NUTS proposed authentication flow, as described in the Generic Functions for Data Exchange – Implementation Guide (Authentication)

The document focuses specifically on the implementation of the instantiate and fetch` calls. It assumes that:

  • One or more search calls have already been performed, and
  • A valid authorization ID has been obtained through those calls.

Console NUTS flow

High-Level Flow Description​

1. Instantiate call​

XIS invokes the instantiate call on the Consolidated API Component.

2. Access Token request preparation (assumption)​

The Consolidated API Component calls the Authorization Server endpoint to initiate the creation of an Access Token Request. As part of this process:

  • A nonce is generated and associated with the request.
  • The Authorization Server possible returns any other unique request-related information, including the nonce.
pas op

This step is an assumption and is not explicitly documented in GFI-04. However, it would appear logical to include such a step to help prevent replay attacks involving the signed VP later in the process.

3. Wallet-signed verifiable presentation​

XIS receives, as a response to the instantiate call, a JWT Verifiable Presentation (JWT-VP) template that includes the nonce (assumed).

XIS then requests the Wallet to sign this [?].

4. Fetch call with signed VP​

XIS invokes the fetch call on the Consolidated API Component, providing the signed JWT-VP (compact presentation) as input.

5. Access Token Request construction​

The Consolidated API Component prepares the Access Token Request with the following elements:

  • The wallet-signed JWT-VP, included as an assertion
  • A client assertion in the form of a JWT-VP, generated and signed by the Consolidated API Component itself.
  • The requested scope, which is added to the Access Token Request

The completed [?] is then sent to the Authorization Server.

Example Access Token Request taken from GFI-04:

POST /oauth/{tenant-id}/token HTTP/1.1
Host: example.com
Content-Type: application/x-www-form-urlencoded
grant_type=urn:ietf:params:oauth:grant-type:jwt-bearer&
assertion=eyJhbGciOiJFUzI1NiIsInR5c&
client_assertion_type=urn:ietf:params:oauth:client-assertion-type:jwt-bearer&
client_assertion=eyJhbGciOiJFUzI1NiIsInR5c&
scope=use-case1 use-case2

6. Access Token issuance and resource request​

If validation is successful:

  • The Consolidated API Component receives an Access Token in the Access Token Response from the Authorization Server.
  • This token is included in the Authorization header as a Bearer token when requesting the resource from the Resource Server.

Example Access Token Response taken from GFI-04:

HTTP/1.1 200 OK
Content-Type: application/json
{
    "access_token": "SlAV32hkKG",
    "token_type": "Bearer",
    "expires_in": 3600,
    "scope": "use-case1 use-case2"
}

7. Resource access validation and response​

The Resource Server validates the Access Token by consulting the Authorization Server.

  • If access is permitted, the Resource Server returns the requested resource.
  • The Consolidated API Component forwards the resource back to XIS.
Laatst bijgewerkt op