API v2 Dokumentation

This is the official documentation of the OPAN® ReST API. It allows developers of business applications for health institutions and Spitex organisations to integrate the OPAN® workflow directly into their software. Use of the API requires a valid key. The key can be requested by sending an email to support@opanspitex.ch and has to be sent as header field "X-ApiKey" in every request. To be able to use the built-in sandbox for testing requests, enter the key in the field at the top right of this page.

Workflow description and further Information (German) | Easy API usage with Postman | Example API calls | Example Workflows | API reference

Since a valid OPAN® application requires quite a bit of information that possibly spans multiple domains of a health institution, this API is designed to be as flexible as possible to accomodate different levels of integration. The initial POST request only requires the most essential of fields, i.e. the desired date, time, zip and location at which the Spitexservice should take place. This information is used to determine which Spitex organisation is responsible and if there is enough time to properly plan and execute the desired service. If everything is okay, a temporary application will be created and returned in the response. Additionally, an URL will be returned that allows manual completion of the temporary application by continuing the process in a web frontend.

This temporary application can then be completed over the API in as many steps as desired, possibly from different parts of an implementing system at different times, by sending PATCH requests to the previously returned resource with additional information. The responses to these requests will indicate whether an application is ready, or which fields are still missing. Once an application has enough information, use the submit request to change the status from temporary to new hence the application will enter the regular OPAN® backend workflow, which is validated by the OPAN® validation team, then assignment to and handling by the proper Spitex® organisation. The response to a PATCH request that successfully completes an application will contain a link that allows the addition and change of application data over the web frontend.

The data of an application that has already been accepted by the OPAN system can still be changed, either over the web frontend using the link mentioned above or by sending further PATCH requests with additional data or changes to the application's resource. Furthermore, additional documents can be attached by using the proper resources as described below.

If you encounter any bugs or notice missing features. Please contact us at support@opanspitex.ch and we'll fix/add them as soon as possible.

Easy API usage with Postman:

In order to explore the API and get up and running quickly, we recommend to use Postman our predefined API collection.

Download the collection | Postman Instructions

Example API calls:

The following files composed in the JSON-Format represent example requests that can be executed with API-Tools.

These are sample files. For a complete list of fields and value sets always use the API-Doc below as a reference.

KIS-Systems (targeting Hospitals):

PIS-Systems (targeting Medical Practices):

Upload a document (generic):

Example workflows:

The following examples describe possible workflows to create an OPAN® application. Steps in parentheses are optional. Also consider the document Workflow description and further Information (German)

Partial integration, some steps completed over web frontend

1. Create new applicationPOST /api/v2/applicationsTemporary application createdResponse contains hash 3fsut3fsfdg806iegr8 and link to web frontend for manual completion
(2.) Add more data over APIPATCH /api/v2/applications/institution/3fsut3fsfdg806iegr8Temporary application updated with new dataResponse contains link to web frontend for manual completion
(3.) Add document filePOST /api/v2/documents/application/3fsut3fsfdg806iegr8Document is attached to temporary application
4. Complete application over web frontendUser completes and sends prepopulated web formsApplication will be validated and assigned to a SpitexOrganisationIf desired, user will receive a mail with a link for manual addition of changes
(5.) Update application over web frontendUser changes values in prepopulated web formsAssigned SpitexOrganisation will be notified about changes
(6.) Add new document file over web frontendUser uploads new document using web formsAssigned SpitexOrganisation will be notified about changes

API reference