Skip to main content

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 Haidy application after jumping off from the EHR software by clicking the respective button in the top right. Additionally, there is an endpoint to generate such a QR code so it can be displayed directly in the EHR software itself.

You can generate a QR code PNG image using the following endpoint:

warning

Always retrieve the QR code image directly from this endpoint. Do not generate the QR code graphic on the client side — only the endpoint is guaranteed to produce a compatible result.

GET https://api.44ai.ch/v2/external-integrations/{integration_id}/qr-code

Query Parameters​

  • unique_id (required): Unique identifier for the consultation or patient in your system.
  • consultation_id (optional): Consultation ID to embed in the QR code.
  • patient_metadata (optional): Patient metadata as a URL-encoded JSON string (same structure as the metadata object described in URL Parameters).

Response​

Returns an image/png QR code. The QR code encodes a JSON object matching the format expected by the Haidy App scanner.

Query parameter to QR payload mapping

The query parameter names (snake_case) differ from the keys embedded in the QR code payload (camelCase):

Query parameterQR code payload key
unique_iduniqueId
consultation_idconsultationId
patient_metadatapatientMetadata
{
  "integration": "<integration_id>",
  "uniqueId": "<unique_id>",
  "patientMetadata": { /* See metadata definition above */ },
  "consultationId": "<consultation_id>"
}

Error Responses​

  • 404 — Integration not found
  • 400 — Invalid patient_metadata JSON or QR content too large
  • 500 — Internal server error

Authorization​

Include the standard Authorization: Bearer <token> header (see Authorization).

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.

info

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:

Add a button in your interface that redirects users to the following URL:

GET    https://haidy.ch/integration?email=<email>&password=<password>&integration=<integration_id>&unique_id=<unique_id>&metadata=<metadata>

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.
    • patient_gender (optional): The patient's gender. Allowed values: male, female, other.

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:

GET https://api.44ai.ch/v2/consultations?integration_id=<integration_id>&unique_id=<unique_id>&page=1&limit=10

Query Parameters​

  • integration_id: (optional)
    Filter consultations by integration ID.
  • unique_id: (optional)
    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.
  • approved: (optional)
    Filter by approval status. Defaults to true.
  • patient_id: (optional)
    Filter by patient context ID.
  • page: (optional)
    The page number for pagination (default is 1).
  • limit: (optional)
    The number of consultations per page (default is 10).

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
        "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
        "patient_context": "string", // Associated patient context ID (optional)
        "user_instructions": "string", // User instructions saved on the consultation (optional)
        "metadata": {        // Consultation metadata (optional)
          "patient_id": "string", // Optional
          "patient_first_name": "string", // Optional
          "patient_last_name": "string",  // Optional
          "patient_birth_date": "string", // Optional
          "patient_gender": "male" | "female" | "other" // Optional
        }
    }
    ]
}
info

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:

Fetch consultation documents in different formats using our API endpoints:

  • JSON Document:
GET https://api.44ai.ch/v2/consultation/<consultation_id>/json
  • Report as PDF:
GET https://api.44ai.ch/v2/consultation/<consultation_id>/report/pdf
  • Report as DOCX:
GET https://api.44ai.ch/v2/consultation/<consultation_id>/report/docx

There is no /v2/consultation/<consultation_id>/report/json endpoint. JSON export is exposed via /v2/consultation/<consultation_id>/json.

Note: The report is only available when the consultation has been processed and a report has been generated.

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:

POST https://api.44ai.ch/v2/consultation/<consultation_id>/mark-as-downloaded

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",
  "patient_gender": "male" // Allowed: "male", "female", "other"
}

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
  patient_gender: "male", // Optional: allowed values: "male", "female", "other"
};

// 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);