KPN Healthcare Messenger API

Introduction

The Healthcare Messenger API gives access to an end-to-end secured messaging platform that allows healthcare professionals to communicate with their co-workers and patients.

The API enables real-time secure messaging and file sharing for 1-on-1 conversations and 1-to-n group chats. It is a HTTP-based RESTful API that uses three-legged OAuth authentication. All API accesses are over HTTPS and the request and response bodies follow the JSON format.


API specification

Test the API on SwaggerHub


Base URL

https://api-prd.kpn.com/communication/kpn/healthcare-messenger


Conceptual model

Conceptual model


Definitions

Auxiliary-conversations

Receiving, sending and managing 1-on-1 conversations with a custom auxiliary identifier.

Auxiliary-groupchats

Receiving, sending and managing group conversations with a custom auxiliary identifier.

Groupchat

Receiving, sending and managing 1-to-n group conversation.

Company

Information of the company and users from the same company as the authenticated user.

Conversations

Receiving, sending and managing 1-on-1 conversations.

Me

The (managing) information related to the authenticated user.

Users

Information on other users and the possibility to invite new users.


Conceptual model of the resources

Resources conceptual model

Auxiliary routes

Auxiliary routes are used for when you want to have conversations and group chats based on your identifier. This identifier is only usable for the OAuth client ID and user company that added it.

When adding the Auxiliary ID to a user or group chat, keep in mind that it will not be checked if it is unique or already present. If the User Auxiliary ID is already being used, it will be overridden. If the same Auxiliary ID is used in the creation of multiple group chats, it will also be associated with each of the unique group chat IDs.


API workflow

Sequence diagram


Features

  • Sandbox: full-fledged capabilities.
  • Security: HTTPS, three-legged OAuth, rate limit at 30 calls per second.
  • Versioning: supports versionless API, version tight. If no version is provided in the header it defaults to the latest version.


Getting started

Make sure you've read Getting Started for more info on how to register your application and start trying out our APIs.

Authentication with three-legged OAuth

For authentication, the API uses a three-legged OAuth flow. This allows your project to obtain an access token by redirecting a user to the KPN Healthcare Messenger login page, where they can authorize your project.

What is three-legged Open Authorization?

Three-legged OAuth is the most common way to delegate access to a protected resource that is owned by a third-party. The 3 legs are:

  • The client application.
  • The API that the client wishes to use (subdivided into an authorization server and resource server).
  • The resource owner (typically an end-user of the client application).

Three-legged OAuth is designed in such a way that the client never obtains access to the resource owner's credentials or any information about their identity.

Three-legged OAuth

Sandbox

During the initial onboarding of your project, an account will be created in the sandbox environment for you to test with. In the sandbox, the user is redirected to a login page from Alterdesk, instead of 'KPN Zorg Messenger'.

User authorization

To let the user authorize your project, point them in your project: https://api-prd.kpn.com/healthcaremessenger_oauth/authorize, with the following GET parameters:

Parameter  Description
response_type  Given the grant type of the request in this case (authorization code), the value of this parameter is required to be set to code.
client_id  The consumer key from your registered project.
redirect_uri  The URI where your user will be redirected to after authorizing your app. This field will be filled with the value of the callback URL from the registration form.
scope  The scopes you want authorization for. It may have multiple, space-delimited values: read-write admin.
state  A unique string that is passed back to the redirect URI on completion of this request. By passing a value (unique to the user you authenticate) and checking when the authentication completes, cross-site request forgery attacks can be prevented.

Combined the request looks like the following example:

^^Request example^^
https://api-prd.kpn.com/healthcaremessenger_oauth/authorize?response_type=code&state=12345&client_id=your_consumer_key&scope=read&redirect_uri=https://www.mytesturl.com/oauth2/callback

After the user accepts the authorization, the Healthcare Messenger uses the redirect URL to redirect back to your site with GET parameters code and state. For example:

^^Redirect URL^^
https://www.mysiteurl.com/oauth2/callback?code=authorization_code&state=12345

If the state does not match, the request is invalid and the authorization process must be aborted!

Get access token

To exchange the authorization code for an access token make a POST call to https://api-prd.kpn.com/healthcaremessenger_oauth/token with the following parameters:

Parameter  Description
client_id  The Client ID from your registered project.
client_secret  The Client secret from your registered your project.
code  The authorization code from the previous step.
grant_type  The type of authorization that is executed, must be authorization_code.
redirect_uri  An URI which must match the originally submitted URI. This field will be filled with the value of the callback URL from the registration form.

The request must have a content-type of project/x-www-form-urlencoded. For example:

^^Request example^^
client_id=your_client_id&client_secret=your_client_secret&code=generated-code&grant_type=authorization_code&redirect_uri=http://www.mysiteurl.com/oaut2/callback

The access token will be present in the JSON response and can be used to call protected API methods on behalf of the user:

^^Request example^^
    {
    "access_token": "generated-access-token",
    "scope": "read write",
    "token_type": "bearer"
    }

To sign the API request use the access_token from the last step and add it to the header:

^^Header example^^
Authorization: Bearer generated-access-token

In the sandbox this access token will expire 3 days after its creation. When applying for production we can set the expiration date of the token to your custom needs!

Start testing and using the API

1. Apply

  1. Go to My API Store.
  2. Click on Sandbox.
  3. In the section Additional APIs to request for testing, go to Healthcare Messenger - KPN.
  4. Click on Request for testing. An e‑mail message opens. Just click on the Send button.

After the testing request has been accepted, you will receive instructions via e‑mail and the Healthcare Messenger API is displayed in the APIs ready for testing section of the sandbox. Use your API Store credentials to test the API in SwaggerHub.

Please be aware that it will take max.1 business day for the onboarding process to finish and the API to be available for use.

2. Fill in callback URL

Fill in the callback URL with your custom authentication URL in the sandbox section of My API store. It is used for the authentication flow of this API. Don't worry, you can always change it later!

Once the callback URL has been changed, it takes max.1 business day to be effective.

3. Start testing in sandbox

A full-fledged sandbox environment is available for testing. It is an identical replica of the production environment. The sandbox runs on an Alterdesk environment. This documentation is based on the 'KPN Zorg Messenger' production environment. The minor differences with the sandbox environment are displayed in a special sandbox dialog.

4. Take API into production

Want to make use of the API's full features and take it into production? Go to the Become a verified customer section and click on Verify my identity. After you have answered a few questions we will onboard the API.

Please be aware that it will take max. 1 business day for the onboarding process to finish and the API to be available for use.

5. Test with HTTP client

If you want to test the API from your local workstation click on the API Specification tab on top of the page. You can also use cURL as an HTTP client. Remember, from this point on, you will have moved from the sandbox environment to production, which implies some changes in the authentication callback URLs.


How to...

Test the API

The API can be tested in SwaggerHub with your Client ID and Client secret in the authentication process.

  1. Click on Authorize.

  2. In the model window, enter your client_id, client_secret and select the permissions to grant.

    Swagger Authorize

  3. Start interacting with the API resources and endpoints.


Return codes

Code Description
200 Success.
201 Created.
202 Accepted.
302 Found. Link in location header.
400 Bad request.
401 Unauthorized.
403 Forbidden.
404 Not found.
405 Method not allowed.
412 Precondition failed.
429 Too many requests.
500 Internal server error.
502 Bad gateway.
503 Service unavailable.


HTTP response headers

The following tables display the standard response headers that are returned with each API response:

Standard response field name Description
sunset This field will be populated with the deprecation details. By default the value is n/a.
api-version Indicates the API version you have used.
quota-interval Used to specify an integer (for example, 1, 2, 5, 60, and so on) that will be paired with the quota-time-unit you specify (minute, hour, day, week, or month) to determine a time period during which the quota use is calculated.
For example, an interval of 24 with a quota-time-unit of hour means that the quota will be calculated over the course of 24 hours.
quota-limit Number of API calls an user can make within a given time period.
If this limit is exceeded, the user will be throttled and API requests will fail.
quota-reset-UTC All quota times are set to the Coordinated Universal Time (UTC) time zone.
quota-time-unit Used to specify the unit of time applicable to the quota.
For example, an interval of 24 with a quota-time-unit of hour means that the quota will be calculated over the course of 24 hours.
quota-used Number of API calls made within the quota.
strict-transport-security The HTTP Strict-Transport-Security (HSTS) response header lets a web site tell browsers that it should only be accessed using HTTPS, instead of using HTTP. All present and future subdomains will be HTTPS for a maximum of 1 year and access is blocked to pages or sub domains that can only be served over HTTP including HSTS preload lists of web browsers.
Strict-Transport-Security: max-age=31536000; includeSubDomains; preload.
Access control field name Description
access-control-allow-credentials Tells browsers whether to expose the response to frontend JavaScript samp when the request's credentials mode (Request.credentials) is include.
When a request's credentials mode (Request.credentials) is include, browsers will only expose the response to frontend JavaScript samp if the Access-Control-Allow-Credentials value is true. Boolean.
access-control-allow-origin Indicates whether the response can be shared with requesting samp from the given origin.
access-control-allow-headers Used in response to a pre-flight request which includes the Access-Control-Request-Headers to indicate which HTTP headers can be used during the actual request.
access-control-max-age Indicates how long the results of a pre-flight request (that is the information contained in the Access-Control-Allow-Methods and Access-Control-Allow-Headers headers) can be cached.
access-control-allow-methods Indicates which HTTP methods are allowed on a particular endpoint for cross-origin requests.
For example: GET, PUT, POST, DELETE.
content-length The Content-Length entity header indicates the size of the entity-body, in bytes, sent to the recipient.
content-type The Content-Type entity header the client what the content type of the returned content actually is.

Mopinion feedback