For developers

# Connect Hysio to your medical record system.

Your medical record system remains the workplace. Start processing with Hysio, receive the result and have the healthcare professional review it before adding it to the record.

[View API documentation](https://api.staging.server03.hysio.nl/apidocs/) [Open Playground](https://epd.hysio.nl)

Contact us directly samenwerking@hysio.nl

[Integration routes](https://hysio.nl/en/connect/#integratieroutes) [Technical starting point](https://hysio.nl/en/connect/#documentatie) [Playground](https://hysio.nl/en/connect/#playground) [Test access](https://hysio.nl/en/connect/#toegang)

## Choose the route that fits your system

Let Hysio handle the input or use your own interface. In both routes, you decide how to process the result in your medical record system.

### Hosted session

Start a session through the API and open the Hysio link in the response. The healthcare professional records a conversation or enters text there, then completes the session.

- Hysio handles the input and processing.

- Receive a draft report and, when available, structured JSON.

### Send text through the API

Keep text entry in your own interface. Send the text to Hysio and receive the result through the API.

- You manage the interface and the text you provide.

- The API documentation describes inputs, statuses and result fields.

## From a session to the right place in the record

Your medical record system maintains the link between the healthcare professional, the care encounter and the record. Hysio supports the documentation.

- ### Start from your system

Choose an available AI assistant. Store the session reference against the appropriate care encounter in your own system.
 
- ### Provide the input

Open the hosted session or send text through the API. Hysio processes the input into a draft report.
 
- ### Receive the result

Receive a postback at your own endpoint or retrieve the result. Match the session reference to the care encounter.
 
- ### Have the draft reviewed

Show the draft to the healthcare professional. Have them review the content and make any necessary changes.
 
- ### Transfer the text

Place the reviewed text in the appropriate record fields. Match your fields and mapping to the output of the selected AI assistant.

## A practical starting point for your integration

Retrieve the available AI assistants, then start a test session. Replace the example placeholders with the base URL, an available id and your API key. Also replace the fictional postback address with your own endpoint.

Base URL for testing` https://api.staging.server03.hysio.nl/api/v1 `

[API reference](https://api.staging.server03.hysio.nl/apidocs/) [Download OpenAPI](https://api.staging.server03.hysio.nl/apidocs/openapi.yaml) [Integration guide (PDF)](https://api.staging.server03.hysio.nl/apidocs/epd-integratie.pdf)

The PDF also contains production examples. Use the staging address above for your test.

### Start a hosted session

````
POST {base_url}/workflows/{workflow_id}/hosted-session
Authorization: Bearer {api_key}
Accept: application/json
Content-Type: application/json
Idempotency-Key: partner-test-voorbeeld-001

{
    "postback_url": "https://dossiersysteem.example/hysio/webhook",
    "collect_answers": true
}
````

A successful request returns HTTP 201, including session\_id, redirect\_url and postback\_secret. Open redirect\_url unchanged, including its fragment, to use the hosted session.

### Receive a postback

````
{
    "session_id": 1841,
    "idempotency_key": "partner-test-voorbeeld-001",
    "status": "completed",
    "output": "## Subjective\nFictional example text from the conversation.",
    "output_json": {
        "subjectief": "Fictional example text from the conversation."
    },
    "output_json_status": "ready"
}
````

Shortened, fictional webhook example. The fields inside output\_json depend on the selected AI assistant. A completed session does not necessarily mean structured JSON is available.

### Discover what is available

Call GET /workflows with your API key. Use the id of the selected AI assistant as workflow\_id in the example; access is associated with your account.

### Verify the postback

Verify X-Hysio-Signature: sha256= followed by the HMAC-SHA256 of the unchanged request body using the returned postback\_secret. Reject an invalid signature. Keep this secret on your server.

### Handle JSON deliberately

Check output\_json\_status before processing JSON. A pending status means conversion is not complete. A not\_configured status means JSON output has not been configured. Also handle processing errors.

### Retry requests carefully

Reuse the same Idempotency-Key when resending the same session creation request. Use a new value for a new session.

Hysio Playground

## Test environment for medical record systems

See how a session starts and the result returns in a fictional medical record system. Explore how it works before building an integration yourself.

Open the playground with an access code. If you do not have one yet, request test access below. An access code is not an API key.

[Open Playground](https://epd.hysio.nl) [Request test access](https://hysio.nl/en/connect/#contact)

Use fictional data only. The playground is a test environment and does not write to a real medical record system.

## From test access to your first API call

To test independently, use a Hysio test account and your own API key. We will arrange access with you.

- ### Request test access

Tell us which medical record system you develop for and what you would like to test. We will help you get the appropriate access and documentation.

- ### Arrange API access

Contact us to arrange test access. We will help you get a test account and the appropriate API access. The API key needs the workflows:read, sessions:create and sessions:read permissions.

- ### Test with fictional input

Use the staging URL, retrieve the available AI assistants and complete a session. Check error responses and how the result is delivered too.

An API key acts on behalf of your Hysio account. The complete key is shown only when you create it. Keep the key on your server and out of frontend code, logs and public examples.

[Security and data processing](https://hysio.nl/en/veiligheid/)[Legal documents (in Dutch)](https://trustcentre.hysio.nl/)

## Tell us what you want to connect

Share your technical question or request playground access. We will help you explore the route that fits your medical record system.

Prefer to email us directly?
samenwerking@hysio.nl

Are you a healthcare professional?

Would you like to know what is possible for your practice? Tell us which medical record system you use so we can discuss the current options.

[Contact us](https://hysio.nl/en/contact/?onderwerp=koppeling)