Healthcare Messenger - KPN


Secure, integrated healthcare communication

Communicate straight from any software system

  • Communication

API Button


What is the Healthcare Messenger from KPN?

The Healthcare Messenger is 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-to-1 conversations and 1-to-n in a group chat format respectively.

Healthcare organizations or independent software vendors can use the Healthcare Messenger API to add communication services to for example existing CRM or EHR software. The API manages the interaction with the KPN Zorg Messenger application to communicate with patients.

With this flexibility, software is enriched without the need to invest into the development of own secure communication functionalities.


Key highlights

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


The Healthcare Messenger is an HTTP-based RESTful API that uses OAuth 2.0 for authorization, more specific three-legged OAuth flow. All API accesses are over HTTPS and the request and response bodies follow the JSON format.

  1. To get started make sure you've read the getting started guide.

  2. Add the Healthcare Messenger product to your application. Please be aware that it will take approximately 1 business day for the onboarding process to finish and the product to be available for use. During this time the Healthcare Messenger product will have a pending status. If, after this time, the product is still pending in your application, please go to the support page and get in touch with us.

  3. Make sure you fill in the callback URL with your custom authentication URL; it is used for the authentication flow of this API. Don't worry, you can always change it later!

    Note: Once the callback URL has been changed, it takes up to one business day to be effective.


  4. 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 instead of “KPN Zorg Messenger”. 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.

  5. Want to make use of the APIs full features and take it into production? Go to your apps and click apply for production!

  6. If you want to test the APIs from your local workstation you can use Postman or our API Reference (powered by SwaggerHub) or cURL as an HTTP client. You can download our Postman collection as an example. If you use the Postman collection or API Reference, make sure you update the environment settings with your credentials. Remember, from this point on, you will have moved from the sandbox environment to production, which implies some changes in the authentication callbacks.

General picture

Sequence diagram



  • API access: HTTPS
  • Authentication: three-legged OAuth
  • Rate limit: 30 calls per second

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

Sandbox During the initial onboarding of your application, 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”.


  1. User Authorization

    To let the user authorize your application, point them in your application to:, 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 application.
    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 in a value (unique to the user you authenticate) and check when the authentication completes, cross-site request forgery attacks can be prevented.

    Combined the request looks like the following example:

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

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

  2. Access Token Issuing

    To exchange the authorization code for an access token make a POST call to with the following parameters:

    Parameter Description
    client_id The consumer key from your registered application.
    client_secret The consumer secret from your registered your application.
    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 application/x-www-form-urlencoded. For example:


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

    "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:

    Authorization: Bearer generated-access-token

    Sandbox 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!

Try it out!

2 interactive environments are provided to test the Healthcare Messenger API: Postman and SwaggerHub. Instructions how to setup the authentication are explained below.

Note: You need to create as many applications as environments you want to test it. If you want to test it on Postman and SwaggerHub, you need to create separate applications for each of them.


You can use Postman to test the authorization flow and get an access token. Please use the following example:


First update your app with the following callback URL

list apps

Make a new request and click on Authorization on the left side of the screen (under GET):

Postman Authorization

Click on Get New Access Token and fill in the following parameters (text after image):

Postman Get Access Token

Field Data
Callback URL
Auth URL https://api-prod/healthcaremessenger_oauth/authorize
Access token URL https://api-prod/healthcaremessenger_oauth/token
Client ID your_consumer_key
Client Secret your_client_secret
Scope the scopes you want; read write or admin

Postman will redirect you to the Healthcare Messenger Login screen where you can log in and authorize the application. After completion this screen will close and you will have a new valid access token to interact with the API.


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

  1. Click on Authentication

    Swagger Authorization

  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!


Me is about the (managing) information related to the authenticated user.

User is about information on other users and the possibility to invite new users.

Company is about the information of the company and users from the same company as the authenticated user.

Conversations is about receiving, sending and managing 1-on-1 conversations.

Groupchats is about receiving, sending and managing group conversations.

Auxiliary-conversations is about receiving, sending and managing 1-on-1 conversations with custom auxiliary identifier.

Auxiliary-groupchats is about receiving, sending and managing group conversations with custom auxiliary identifier.

Conceptual model of the resources

Healthcare Conceptual Model

Auxiliary Routes

The Auxiliary Routes are used for when you want to get conversations and groupchats based on your identifier. This identifier is only usable for the OAuth Client ID and User Company that added it.

Note: when adding the Auxiliary ID to a user or groupchat keep in mind that the ID 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 Groupchats, this Auxiliary ID will be associated with each of the unique Groupchat IDs.

Return codes

Code Meaning
200 Success
201 Created
202 Accepted
302 Found. Link in Location Header
302 Found. Link in Location Header.
401 Unauthorized
403 Forbidden
404 Not Found
429 Too many requests
500 Internal server error
503 Service unavailable