Getting started with ZIBs and FHIR

We will assume that you have an Ons API integration, at least on the development stage. We will link to the relevant parts of the FHIR specification where applicable.

Overview of available endpoints

We supply several FHIR endpoints that will always return ZIB profiles. For all available profiles, see simplifier. For the supported profiles/ZIBs, see the ZIBs page. These endpoints are available in the Ons API Dashboard, all starting with /t/fhir, followed by the resource. Two endpoints are available per resource: a read endpoint (such as /t/fhir/Patient/{id}) and a search endpoint (/t/fhir/Patient).

Read endpoints

The read endpoints only allow gathering a single resource based on its id. These ids often consist of some kind of uuid. This means most of the time that they are not the initial entrypoint, but should rather be used to gather additional references after searching for a resource. An example call would be:

https://api-development.ons.io/t/fhir/Patient/Client.500f9b5e-9248-4c0b-b96d-3bb75d3148ce

Search endpoints

The search endpoints will always return a bundle, which contains a list of all resources found through the search operation. The search parameters are passed in as query parameters. Several of these are available for each resource and to get a full overview of available query parameters per resource, you can query the capability statement: /t/fhir/metadata.

Query parameters

Some general query parameters are available in (almost) all resources:

• _id is an alias for the read endpoint. It does allow usage of some of the other capabilities of the search endpoint so there are certainly usecases where this parameter is relevant.

• identifier allows searching based on some identifier of the resource. This is a token parameter, which means it is built up of two parts, separated by a pipe (|). The first part is the system defining the type of this identifier (e.g., social security number). The second part is the actual value or code.

  As an example, a patient ZIB can be gathered based on their social security number:

  https://api-development.ons.io/t/fhir/Patient?identifier=http://fhir.nl/fhir/NamingSystem/bsn|077461848

  Here, http://fhir.nl/fhir/NamingSystem/bsn is the system and 077461848 is the value. For more information on systems and codes, see the information described later in this article.

• subject, patient and subscriber are examples of parameters that allow filtering on references, in most cases a patient. We support filtering based on the id of the reference or on one of its supported identifiers. This parameter is, in most cases, the primary point of entry when gathering ZIBs around a specific patient.

  It can be called in two ways. We will give an example of both in the context of Observation resources. The first example gathers all observations for a specific patient, based on the id of that patient:

  https://api-development.ons.io/t/fhir/Observation?subject=Patient/Client.500f9b5e-9248-4c0b-b96d-3bb75d3148ce

  Another possibility is to gather all observations based on the social security number of the patient:

  https://api-development.ons.io/t/fhir/Observation?patient.identifier=http://fhir.nl/fhir/NamingSystem/bsn|432047669

• code is similar to identifier in that it consists of a combination of system and value. However, code gathers all resources that fall within a certain category. An example gathering the living situation of a specific patient based on its social security number:

  https://api-development.ons.io/t/fhir/Observation?code=http://snomed.info/sct|365470003&patient.identifier=http://fhir.nl/fhir/NamingSystem/bsn|432047669

• _include allows direct incorporation of a referenced resource in the returned bundle. Normally, a referenced resource is only added as an id. As an example, this call will return all insurances of a Patient with a certain social security number, and also include that patient itself in the returned bundle:

  https://api-development.ons.io/t/fhir/Coverage?subscriber.identifier=http://fhir.nl/fhir/NamingSystem/bsn|556673682&_include=Coverage:payor:Patient

In some cases the pipe will need to be escaped by using %7C.

Supported identifiers

We support searching based on identifiers for Organizations, Patients and Practitioners.

Systems and codes

The systems used in codes and categories are always either a snomed code, or local (pointing to internal categories). The latter is only available for observations. Snomed codes can be built up as http://snomed.info/sct|365470003 or urn:oid:2.16.840.1.113883.6.96|365470003, where in this case 365470003 refers to the living situation of the patient.

In the case of observations, it is also possible to search based on the reportTypeId of the reports as they are available through our traditional API endpoints. A list of available report types can be found by calling /t/dossier/report_types

Last-n

One special endpoint is available for the Observation resource: $lastn. This endpoint will return the last number of observations of each type related to a certain patient. If no n is provided through the max query parameter, only the most recent observation of each type is returned. Example usage:

https://api-development.ons.io/t/fhir/Observation/$lastn?max=2&subject=Client.500f9b5e-9248-4c0b-b96d-3bb75d3148ce

If a code is provided, only the last n of that specific type of observation are returned:

https://api-development.ons.io/t/fhir/Observation/$lastn?max=3&subject=Client.500f9b5e-9248-4c0b-b96d-3bb75d3148ce&code=http://nedap.com/fhir/NamingSystem/local|report