PIS Integration
Haidy offers a simple way to integrate with Patient Information Systems (PIS). This guide explains how to integrate with a PIS using Haidy and the Haidy App. If you prefer to connect directly to our API, please refer to the API documentation.
Integration Flow Overview
Prerequisites
- Integration ID:
You must obtain an integration ID to connect to Haidy. Please contact us at api@44ai.ch to receive your integration credentials.
0. Optional: Patient Context Synchronization
Haidy offers multiple ways to synchronize patient data to provide better context for consultations:
API-Based Synchronization
See the Patient Context guide for details on how to synchronize patient data from your PIS to Haidy before recording consultations. This method accepts text, PDF, images, and FHIR data. The endpoints support updates, so data can be sent again for subsequent consultations - Haidy handles deduplication automatically.
QR Code Integration
When using the Haidy Smartphone App, doctors can scan a QR Code in the EHR-Software that contains patient information before starting the consultation. This method requires custom implementation by 44ai to map QR Code data to our internal system, but requires no extra effort from the PIS system.
E-Mail Import
Send a HIN email to a specified email address with a predefined subject. All documents in the attachment will be parsed and added to a (new) patient context.
Manual Upload
If no integration is available, users can create a new patient in Haidy Reporter and import files via file upload.
Note: All above methods result in patient creation in Haidy Reporter. Patients are identified using an "external_id" - if the EHR software doesn't set this value, Haidy generates one automatically. To ensure automatic linking during consultations, use the patient's external_id as the unique_id in the consultation.
1. Starting Report Generation
Haidy offers several ways to initiate report generation:
URL Redirect Integration (Recommended)
Add a button in your interface that redirects users to the following URL:
URL Parameters
email:
The user's email address.password (optional):
The user's password. If no password is provided, the user will be prompted to log in if they are not already logged in. We do not recommend including passwords in URLs.integration:
Your integration ID, which you received from us.unique_id:
A unique identifier for the consultation or patient in your system.metadata (optional):
A JSON object with the following fields:patient_id(optional): Additional patient identifier in your system.patient_first_name(optional): The patient's first name.patient_last_name(optional): The patient's last name.patient_birth_date(optional): The patient's birth date.
Note: The metadata parameter should be URL encoded. See the Metadata URL Encoding section for an example.
Once the user is redirected to the Haidy Web App, they can record a consultation. After recording, the user must approve the consultation in the web app, making it available for retrieval by your system through the dedicated endpoints.
Manual Patient Selection
Users can open the Haidy interface (web or app) and select a patient that was created using any of the synchronization methods above.
QR Code via App
When using the QR Code option with the Haidy App, the patient is automatically selected.
Planned Consultations
Import planned consultations (like calendar entries) via API into Haidy Reporter. Upcoming consultations are shown prominently to doctors.
2. Fetching Approved Consultations
After a consultation is approved, you can retrieve a list of approved (and not yet downloaded) consultations with the following endpoint:
Query Parameters
- integration_id: (required)
Your integration ID. - unique_id: (required)
Filter consultations by the unique ID provided in the consultation creation request. This could be, for example, a patient ID or an external consultation ID. Leave empty to fetch all consultations. - page: (optional)
The page number for pagination (default is1). - limit: (optional)
The number of consultations per page (default is10).
Sample Response
{
"total": 1, // Total number of consultations
"page": 1, // Current page number
"limit": 10, // Consultations per page
"data": [
{
"id": "string", // Consultation ID
"date": "string", // Date of the consultation
"notes": "string", // Consultation notes
"report_text": "string", // Text version of the report (may be null if not available)
"report_html": "string", // HTML version of the report (may be null if not available)
"unique_id": "string", // Unique ID provided in the create consultation request
"metadata": { // Consultation metadata (optional)
"patient_id": "string", // Optional
"patient_first_name": "string", // Optional
"patient_last_name": "string", // Optional
"patient_birth_date": "string" // Optional
}
}
]
}
We also offer webhooks to notify your system when a consultation is approved. Contact us to discuss setting up webhooks for your integration.
3. Syncing Reports Back to EHR
Haidy offers various methods to export and sync reports back to your EHR system:
API-Based Retrieval (Recommended for Integrations)
Fetch consultation documents in different formats using our API endpoints:
- JSON Document:
- Report as TXT:
- Report as PDF:
- Report as DOCX:
Note: The report is only available when the consultation has been processed and a report has been generated.
- Notes as TXT:
- Notes as PDF:
Replace <consultation_id> with the appropriate consultation identifier.
Alternative Export Methods
- Copy & Paste: Users can copy report content directly from the Haidy interface
- E-Mail Export: Reports can be exported and sent via email
- PDF File Export: Download reports as PDF files directly from the interface
- Webhook Notifications: Receive active notifications when new reports are available (contact us to set up webhooks)
4. Marking a Consultation as Downloaded
Once your system has processed a consultation, you can mark it as downloaded so that it no longer appears in subsequent fetch requests:
Replace <consultation_id> with the consultation ID you wish to mark as downloaded.
Note that as downloaded marked consultations will not appear in the list response anymore. However they can still be accessed directly via their consultation ID.
Authorization
For all direct API requests, ensure that you include the following HTTP header:
Authorization: Bearer <token>
Replace <token> with the user's authentication token.
By following these steps, you can seamlessly integrate with the Haidy platform to record and manage patient consultations. If you have any questions or require further assistance, please contact our support team at api@44ai.ch.
Metadata URL Encoding
The metadata parameter should be URL encoded. For example, the following JSON object:
{
"patient_id": "123",
"patient_first_name": "John",
"patient_last_name": "Doe",
"patient_birth_date": "1990-01-01"
}
In JavaScript, you can encode it as follows:
// Example input object simulating metadataJSON
const metadata = {
patient_id: "12345",
patient_birth_date: "1980-01-01", // Optional: remove or leave undefined if not available
patient_first_name: "John", // Optional: remove or leave undefined if not available
patient_last_name: "Doe", // Optional: remove or leave undefined if not available
};
// JSON.stringify automatically omits properties with undefined values
const jsonStr = JSON.stringify(metadata);
// URL-encode the JSON string
const encodedJson = encodeURIComponent(jsonStr);
// Construct the URL with the patientMetadata query parameter
const baseUrl =
"https://haidy.ch/integration?email=<email>&password=<password>&integration=<integration_id>&unique_id=<unique_id>&";
const url = `${baseUrl}metadata=${encodedJson}`;
console.log("Generated URL:");
console.log(url);