Start your integration
This getting started guide shows you how to easily set up an integration between your solution and our Sandbox. Follow the steps and you will be sending test messages within no time!
In order to set up an integration with the Founda Sandbox environment, you will need a developer account on the Founda Platform. This developer account is free and can be created for you if you fill in this form.
If you already received an account, jump ahead to the Building-your-integration steps below.
Some background
The Founda Health Platform enables Application Providers to connect to healthcare Provider Organization systems through a uniform set of interfaces. Application Providers integrate once with the Founda Health Platform to provide their services to different Provider Organizations.
The Application Provider is represented in the platform through a Client. This Client defines the specific configurations, (FHIR) scopes and subscriptions the application requires.
Scope: The Combination of a FHIR Resource (e.g. Patient or Observation) and the Restful actions (Create, Update, Read, Delete, etc.) are referred to as a "scope".
A Client can either be a Test Client, interacting with a Sandbox, or a Production Client, interacting with a Provider Organization’s source system (e.g. EHR).
- When a Test Client is created, a sandbox Provider Organization will automatically be created with scopes permitting all operations upon all FHIR 4 resources. This requires no further approval from a Provider Organization.
- When a Production Client is created, the request for this Client defines the (FHIR) scopes that the Application Provider requires. A Production Client must always be authorized by a Provider Organization, accepting the requested (FHIR) scopes, before it is allowed to interact with that Provider.
Build your integration
Once you have received your developer account to the Founda Platform you can start building your integration. With the developer account you have access to an integration sandbox which will act as your healthcare organization to integrate with.
Step 1: Determine scope
The gateway and sandbox support all the resources, extensions, and query parameters that are listed in this documentation. In order to onboard your application to the Founda Health Platform you create a “client profile” reflecting the FHIR resources and operations your application requires. You can find all the required steps in the Console to set up your own client profile.
During the process of creating your Client, you will receive your Client Credentials, be sure to store them safely as you need them in the following steps.
If your Client was created by Founda you will receive the Client Credentials via 1Password and this step can be skipped.
Step 2: Authentication
Founda supports the following authentication mechanisms for making requests to the API gateway:
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 Client, access will be denied. More information about the Bearer Token specifications can be found here.
OAuth2
In order to authenticate and authorize with OAuth2, you will need your Client ID and Client Secret. There are two ways in which you received these Client Credentials:
- You created your own Client Profile in Step 1 according the steps in the Console Tutorial and safely stored your Client Credentials during that process.
- Your Client was created by Founda and you received an email with a 1Password link, containing your (test) Client Credentials.
With the Client Credentials, you can request an access and refresh token. The access token must be included in any request to the gateway. Refresh tokens are used to request new tokens. Access tokens expire after 60 minutes. Access tokens and refresh tokens can be generated using the following URLs, depending on the region your organization is hosted in:
- https://identity-oauth.eu.founda.com/oauth2/token
- https://identity-oauth.us.founda.com/oauth2/token
If you want a step-by-step tutorial on how to authenticate and authorize with OAuth2, you can follow the steps in the Authentication with OAuth2.0 tutorial.
Step 3: Integrate
Integrate first with your sandbox environment. Once your application is integrated with the sandbox environment it can be connected to multiple organizations. To do so, you share your client’s Client exchange ID with the Provider Organization you want to connect with. The Provider Organization must authorize your client before health data can be exchanged.
API URLs
Connecting to a different healthcare organization is as easy as calling a different URL.
The API URL is structured as: https://api.eu.founda.com/1/health/organizations/{organizationId}/fhir/4/
Where {organizationId} is the identifier of the Provider Organization you want to connect to. After the URL you can refer to resources such as: https://api.eu.founda.com/1/health/organizations/{organizationId}/fhir/4/Patient
Note that resources are capital sensitive.
Sandbox data
Your sandbox can support all the resources, extensions and query parameters that are listed in the documentation. Since not all Provider Systems offer full FHIR support it is possible to configure what FHIR resource the Sandbox exposes.
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
Founda has implemented the most flexible structure of capturing log information, that allows being compliant to a multitude of international healthcare data compliance standards, leveraging the FHIR AuditEvent.
Logs related to your API requests can be accessed through the Console, see the Audit Record Repository tutorial.
Check out our integration guide for our IHE ATNA compliant AuditEvent APIs Audit Record Repository
