Juvoly V2 API Documentation

This page provides an overview of how to interact with our API. For detailed code examples, check out the following links:

Overview

To use the Juvoly API, follow these two steps:

  1. Create a session: Use your client ID and API key to establish a session.
  2. Open a WebSocket: Initiate the WebSocket for the session to begin transcribing and summarizing.

There are two types of API keys. Both can be used for all functionality in the API:

The user API key is likely relevant if you’re building an HIS/EPD/EHR integration. This adds an optional step to follow first:

  1. (optional) Request user API key: Check if user has a juvoly subscription and get user-specific API-key.

See an overview of the interaction below:

interaction

Create a Session

To begin, you will need a valid API key. If you don’t have one, you can request it by emailing info@juvoly.nl.

Note:
Your API key is private and should not be shared with anyone outside your organization. Ensure that end-users are not able to extract the API key from your application if it is being executed client side.

Sending the Request

To create a session, send an HTTP POST request to the following endpoint:
https://services.juvoly.nl/api/v2/rest/session

You’ll need to provide the following headers with your request:

X-Juvoly-Api-Key: <api-key>
X-Juvoly-Client-Id: <client-id>
Content-Type:: application/json

The body should be an empty json object:

{}

Processing the response

After successfully requesting access, you should receive an HTTP 200 OK response with the following body:

{
    "clientId": "<client-id>",
    "sessionId": "<session-id>",
    "sessionCreateTime": "<ISO 8601 timestamp>",
    "sessionClaimTime": null
}

The most important value in the response is the sessionId, which you will need to establish a WebSocket connection later.

Note:

Open a WebSocket

After obtaining the sessionId, you can establish a WebSocket connection. This can be done directly from the client, such as a web browser. There’s no need to redirect audio through your back-end.

Create the Connection

To create the connection, use the following WebSocket URL:
wss://services.juvoly.nl/api/v2/socket/<model>

For the model parameter you can choose from the values below. Choose generic if in doubt.

name Experimental Comment
generic no Default. Improved support for medical terms. Only supports Dutch.
multilingual no Supports 90+ languages.
kolibri yes Under development. Faster and more precise version of the “generic” model.
radiology no Special support for radiology style transcripts.

You’ll need to provide the following subprotocol headers:

Note:
The headers are specified in line with https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Sec-WebSocket-Protocol. The order of the values is important.

After successfully connecting, wait for a ready message from the server before sending any other data. The message will look like this:

{
    "type": "ready"
}

Using PCM

The websocket API supports sending audio blobs in most common formats like wav/flac/mp3.

If you want to publish audio in the PCM format you will need to specify the url parameter encoding=PCM. So to create the connection, use the following WebSocket URL instead:
wss://services.juvoly.nl/api/v2/socket/<model>?encoding=PCM

Start Transcribing

When you receive the “ready” message, you can begin sending audio blobs over the WebSocket connection. The audio data can be transmitted directly as raw bytes, without any additional protocol. For more details on how to send audio blobs, check out the language-specific examples linked at the beginning of this page.

After sending audio blobs, you will begin receiving transcription utterances in real time. While audio is being transcribed you will also receive utterances that did not finish processing yet. This will be indicated by the completed field being set to false. The content may change in subsequent messages until the completed value is received.

Example completed message:

{
    "type": "transcript",
    "utterance":
    {
        "id": "0",
        "sentence": "Goedemiddag.",
        "words":
        [
        	{
                "word": "Goedemiddag.",
                "start": 8.48,
                "end": 9.12,
            }
        ]
    },
    "completed": true
}

Example intermediate update that is not yet finalized and completed:

{
    "type": "transcript",
    "utterance":
    {
        "id": "1",
        "sentence": "Wat heeft",
        "words":
        [
        	{
                "start": 9.84,
                "end": 9.92,
                "word": "Wat"
            },
            {
                "start": 10.08,
                "end": 10.16,
                "word": "heeft"
            }
        ]
    },
    "completed": false
}

Request Summarization

To request a summarization, send a request over the WebSocket connection. Currently we only support summaries in the SOEP form. The request format should be as follows:

{
    "type": "summarizeSoep"
}

Shortly after submitting your request, you will receive a message containing the summary. It will look like the example below:

{
    "type": "summarySoep",
    "summary":
    {
        "episodes":
        [
            {
                "subjective": "Keelpijn en hoofdpijn al 2 weken.",
                "objective": "",
                "evaluation": "Mogelijke infectie van de keel.",
                "plan": "Antibiotica voorgeschreven."
            },
            {
                "subjective": "Plekje op de voet, behandeling gewenst.",
                "objective": "",
                "evaluation": "Niet gedefinieerd, verdere evaluatie nodig.",
                "plan": "Verwijzing naar dermatoloog."
            }
        ]
    }
}

Subscribe to Information

It is possible to subscribe to information that is extracted live from the transcript. Information consists of:

This can be done by sending the following message:

{
    "type": "subscribe",
    "subscription":
    {
        "type": "information"
    }
}

After doing so you will start receiving information if relevant information is found. It is possible that no relevant information is found so you won’t receive information messages. Example information:

{
    "type": "information",
    "codings":
    [
        {
            "system": "snomed",
            "code": "392570002",
            "description": "bevinding betreffende bloeddruk"
        },
        {
            "system": "icpc",
            "code": "K29",
            "description": "Andere symptomen/klachten hartvaatstelsel"
        }
    ],
    "resources":
    [
        {
            "link": "https://www.thuisarts.nl/hoge-bloeddruk",
            "description": "Hoge bloeddruk",
            "origin": "Thuisarts"
        },
        {
            "link": "https://richtlijnen.nhg.org/standaarden/cardiovasculair-risicomanagement",
            "description": "",
            "origin": "NHG"
        }
    ],
    "measurements":
    [
        {
            "description": "Bloeddruk",
            "value": "140/90",
            "unit": "mmHg"
        }
    ]
}

Request User API Key

If you’re integrating a HIS/EPD/EHR you likely first want to request a user-specific API key. This makes sure that:

To request the user API key you will need to use an API key first.

Please reach out to info@juvoly.nl if you’re not sure if this is relevant to you.

Sending the request

To request the user API key, send an HTTP GET request to the following endpoint:
https://services.juvoly.nl/api/v2/rest/auth/user-api-key

You’ll need to specify the following headers:

X-Juvoly-Api-Key: <api-key>
X-Juvoly-Client-Id: <client-id>
Authorization: Basic <userEmail:userPassword>  // base64 encoded value

Some notes on the headers:

After successfully requesting the user API key, you should receive an HTTP 200 OK response with the following body:

{
    "userApiKey": "<user-api-key>"
}

If the user credentials are not valid or the user does not have a subscription you will receive an HTTP 401 Unauthorized response.