Healthcare gateway overview

The Founda Healthcare Gateway is an API gateway (served as SaaS) that connects applications with healthcare data. The gateway takes care of receiving, processing and sending healthcare data.

alt text

Applications integrate once and then provide their services to different Healthcare Organisations. Applications on the Healthcare Gateway have one stable API to connect to various Healthcare Organisation’s systems. The gateway securely exposes multiple standardized information interfaces such as FHIR.

The Healthcare Gateway is a standard-first platform and vendor agnostic. Our gateway offers prebuilt and reusable integrations with healthcare systems. We solve the integration hassle, creating a win-win situation for healthcare as a whole.


Term Meaning
Developer The person or organisation who builds and maintains the healthcare application that integrates into the gateway.
Application The system that uses Founda’s gateway to integrate with data providers.
Healthcare Organisation An organisation that delivers healthcare and operates a data provider.
Provider System The (EHR) system of the healthcare practitioner.
Healthcare Gateway The set of non-custom APIs Founda exposes to interact with healthcare providers’ data. The Founda FHIR API is a subset of these APIs.

Getting started guide

Get a developer account

Get started with Founda by creating a free developer account. Your developer account gives you access to the Healthcare gateway. To request a developer account fill out this form.

Build your integration

Start building your integration using your developer account. With your developer account you will also be provided an integration sandbox which will act as your healthcare organisation while you integrate.

Step 1: Determine scope

The healthcare gateway and sandbox support all the resources, extensions, and query parameters that are listed in the documentation. Not every healthcare organisation supports all resources and operations in their production environment.

Step 2: Authentication

When using the healthcare gateway your requests will have to be authorized. Founda supports the following authentication mechanisms:

  • Bearer Token
  • Oauth2

Bearer Token

To use bearer tokens include them in the Header of your request: "Authorization" with a value of Bearer <token>.

If a token is not present, or the resource is not part of the scope of the consumer access will be denied. For sandbox integrations this token does not expire.

More information about the specifications.


The application is provided with an Oauth2 client ID and client secret. With these the application can request an access token and refresh token. The token must be included in any request to the Healthcare Gateway. Refresh tokens are used to request new tokens. Access tokens expire after 60 minutes.

Access tokens and refresh tokens can be generated using More information about the specifications.

Step 3: integrate

Integrate first with your sandbox environment. Once your application is integrated with the sandbox environment it can be connected to multiple healthcare organisations.


Founda provides a FHIR interface to every healthcare organisation. Your application integrates with the API. Connecting to a different Healthcare Organisation is as easy as calling a different URL.

The API URL is structured as:[Healthcare_Organisation]/fhir/4/

Where [Healthcare_Organisation] is the identifier of the Healthcare Organisation you want to connect to. After the URL you can refer to resources such as:[Healthcare_Organisation]/fhir/4/Patient

Resources are capital sensitive.

alt text

Sandbox data

Your sandbox can support all the resources, extensions and query parameters that are listed in the documentation. Not every Healthcare Organisation supports all resources and operations in their production environment.

A sandbox is provided with a preliminary set of test data, if you need additional test data, or test data using supported extensions, please add them to your sandbox by creating new resource instances using your own test data.

Step 4: logging

Different national standards require logging of parameters that are relevant to particular operations that may not be part of the request itself. For example, when requesting an observation of a patient via the Healthcare Gateway it may be required to log the treatment relationship and name of the doctor who is requesting the data. In order to be able to log this data in accordance with various national regulations the LOG-CDATA header and LOG-CDATA-FORMAT header are used.


This header can contain a JSON object or sets of key:value pairs encoded according to attribute-value pairs in URIs. The content of these values is free to define except for reserved terms. All content will be logged. This field is optional.

Reserved keys

No key in the JSON object or in the key:value pairs may begin with _. Any value prepended with _ is reserved for future use.


If this header is not present, the structure of the LOG-CDATA header is assumed to be key:value pairs. If the LOG-CDATA-FORMAT header is present it will be used to interpret the structure of the LOG-CDATA header.

  • If the value of the LOG-CDATA-FORMAT is kv the structure of the LOG-CDATA header will be interpreted as key:value pairs.

  • If the value of the LOG-CDATA-FORMAT is json the structure of the LOG-CDATA header will be interpreted as a JSON object.

Example: logging responsible practitioner

log-cdata: "initiating-practitioner=Dr Dave Davenport,responsible-practitioner=Dr Susan O’Neil"

This will be available in your logs and Healthcare Organisation logs for this API call.

Request access to live healthcare organisations

Before you can connect your application to a Healthcare Organisation, the Healthcare Organisation must approve your connection with Founda. Once the Healthcare Organisation completes this step your application can interact with the resources at the Healthcare Organisation.