Juvoly V2 HTTP API

To make any HTTP request to our API, you will need a valid API key. See also Authorization for more information on the two types of API keys we support.

Any HTTP request will require at least the following headers:

X-Juvoly-Api-Key: <api-key>
X-Juvoly-Client-Id: <client-id>

Auth Endpoint for User API Key Request

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

Extra Headers

Authorization: Basic <userEmail:userPassword>  // base64 encoded value

Some notes on the headers:

• The used for `X-Juvoly-Api-Key` is your organizations master API key. It is not possible to request a user API key with another user API key. After the user API key is retrieved you want to use that key for further interactions and can ignore the master API key.
• The Authorization header follows the standard implementation with a base64 encoded value. See for example https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Authorization. Only ‘Basic’ is supported.

Response

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.

Session Endpoint for Creating WebSocket Sessions

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

Extra Headers

Content-Type: application/json

Body

The body should be an empty json object:

{}

Response

After successfully requesting a session, 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.

Important notes:

• The sessionId expires ten minutes after creation or immediately upon opening a WebSocket connection.
• As the sessionId is sensitive information, do not share it with third parties. It is fine to store it in memory on the frontend.

Speech Endpoint for Audio Transcription

To transcribe an audio file, send an HTTP POST request to the following endpoint:
https://services.juvoly.nl/api/v2/rest/speech/transcript?model=MODEL_NAME

URL Parameters

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.

Extra Headers

Content-Type: audio/mpeg

Body

The body should be the raw bytes of an audio

Response

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

{
    "utterances": [
        {
            "id": "",
            "sentence": "",
            "words": [
                {
                    "word": "",
                    "start": 0,
                    "end": 0.1
                }
            ]
        }
    ]
}

Template Endpoint

To look up which templates (document structures) are available for mapping, send an HTTP GET request to the following endpoint:
https://services.juvoly.nl/api/v2/rest/map/template

Response

After successfully requesting the templates, you should receive an HTTP 200 OK response with a body similar to the following structure:

[
    {
        "key": "soap",
        "name": "SOEP",
        "description": "Het standaardverslag voor de eerstelijnszorg (huisartsen). De aanbevolen keuze voor een SOEP.",
        "repeating": true,
        "fields": [
            {
                "key": "subjective",
                "name": "Subjectief",
                "description": "Mening van patiënt of iemand anders dan jij"
            },
            {
                "key": "objective",
                "name": "Objectief",
                "description": "Wat jij objectiveert"
            },
            {
                "key": "assessment",
                "name": "Evaluatie",
                "description": "(voorlopige) diagnose"
            },
            {
                "key": "plan",
                "name": "Plan",
                "description": "(voorlopig) beleid"
            }
        ],
        "parameters": [
            {
                "key": "episodeCount",
                "name": "Aantal Episodes",
                "description": "automatisch",
                "defaultValueKey": "automatic",
                "values": [
                    {
                        "key": "automatic",
                        "name": "Automatisch"
                    },
                    {
                        "key": "1",
                        "name": "1"
                    },
                    {
                        "key": "2",
                        "name": "2"
                    },
                    {
                        "key": "3",
                        "name": "3"
                    }
                ]
            }
        ]
    }
]

Some notes on the different properties:

• repeating indicates whether multiple documents can result from a map call for this template.
• key is generally a unique identifier that is not expected to change and can be used to link mapping output to the template structure.
• name and description are human readable values for display purposes.
• parameters can be used to customize the output of a mapping.

Map Endpoint for Document Mapping Including Summarization

To map text to a document like for example a summary, send an HTTP POST request to the following endpoint:
https://services.juvoly.nl/api/v2/rest/map

Extra Headers

Content-Type: application/json

Body

The body should follow the structure below:

{
    "text": "<text>",
    "templateKey": "template-key>",
    "templateParameters": {
        "<parameter-key>": "<parameter-value>"
    }
}

Note that the template key is generally expected to be chosen based on the returned templates from the templates endpoint. If you’re just looking for a SOAP/SOEP summary you can fill in soap as template key.

The parameters are optional and can be omitted if in doubt.

Response

After successfully mapping the text, you should receive an HTTP 200 OK response with a body similar to the following:

{
    "documents": [
        {
            "fields": [
                {
                    "key": "subjective",
                    "name": "Subjectief",
                    "value": ""
                },
                {
                    "key": "objective",
                    "name": "Objectief",
                    "value": ""
                },
                {
                    "key": "assessment",
                    "name": "Evaluatie",
                    "value": "Scabiës"
                },
                {
                    "key": "plan",
                    "name": "Plan",
                    "value": ""
                }
            ],
            "resources": []
        }
    ]
}

Note that this is just an example for a mapping to a template with SOAP structure. The fields could be anything depending on the chosen template.

The key is a unique identifier of the field and can be relied upon to always remain the same. The name is a human-readable name of the field and could potentially change.

Map Custom Endpoint for Custom Document Mapping

To map text to a document with a custom structure, send an HTTP POST request to the following endpoint:
https://services.juvoly.nl/api/v2/rest/map/custom

Extra Headers

Content-Type: application/json

Body

The body should follow the structure below:

{
  "text": "<text>",
  "template": {
    "focus": "<general document focus>",
    "style": "<general document style>",
    "repeating": <true if more than one document can result from a mapping>,
    "fields": [
      {
        "key": "<field key - to link to examples>",
        "name": "<field name - any string of your choice>",
        "focus": "<field focus - what should be described>",
        "style": "<field style - any preferences for the writing style>"
      }
    ],
    "examples": [
      {
        "<field key>": "<example value>"
      },
      {
        "<field key>": "<example value>"
      }
    ]
  }
}

Response

After successfully mapping the text, you should receive an HTTP 200 OK response with a body similar to the following:

{
    "documents": [
        {
            "fields": [
                {
                    "key": "<field key>",
                    "name": "<field name>",
                    "value": ""
                }
            ],
            "resources": []
        }
    ]
}