Skip to content

Integration Guide

MD.ai reporting can be effortlessly integrated into any PACS, RIS, or web application using iframes. By leveraging our secure token-based authentication, you can enable direct access to reports within an iframe embedded in your application. This eliminates the need for users to log in separately on MD.ai, streamlining workflows and enhancing user experience.

Each site (SiteID) provisioned by MD.ai is assigned site administrators who have full control over the reports being generated within the system. As a site admin, you have the ability to assign reports to specific users by passing the necessary authentication token and user details in your POST request. This allows the users, who are already logged in to your system, to directly access the reporting interface and begin dictating reports immediately without the need for separate login credentials.

We will work with your team to designate site administrators and they will then be able to configure and manage launching these reports within your iframe.

Embedding MD.ai reporting as an iframe

To embed MD.ai reporting within your application using iframes, follow these steps -

First, you need to generate a report link by sending a POST request using the MD.ai Reporting API. In addition to all the relevant clinical tags mentioned, your request MUST include the following additional tags -

  Auth: The MD.ai access token from a site admin of your site on MD.ai. This is important and only the token from one of the site admin's will work.
  UserName: The name of the user to whom the report will be assigned.
  UserEmail: The email address of the user who will be working on the report.

Example POST Request

POST /api/report/launch/clinical HTTP/1.1
Host: chat.md.ai
Content-Type: application/json
x-access-token: YOUR_ACCESS_TOKEN

{
    "tags": {
        "SiteID": "test",
        "PatientMRN": "test-mrn",
        "Accession": "test-accession",
        "ReturnFormat": "HL7",
        "PatientName": "John Doe",
        "PatientBirthDate": "01021975",
        "PatientAge": "50",
        "PatientSex": "M",
        "Modality": "CT",
        "BodyPartExamined": "Abdomen",
        "StudyDescription": "CT abdomen w/wo contrast",
        "StudyDate": "05022024",
        "StudyTime": "122009",
        "StudyInstanceUID": "1.2.1.2",
        "ReasonForExam": "History of colon cancer and new onset abdominal pain.",
        "Auth": "SITE_ADMIN_MDAI_ACCESS_TOKEN",
        "UserName": "testphysician",
        "UserEmail": "testphysician@md.ai"
    },
    "result": "link",
}

Note

Please note the inclusion of the Auth, UserName, and UserEmail parameters within the tags. The Auth parameter must contain the access token from a site admin. The report will not launch in your iframe if these parameters are missing. Therefore, only site admins can create authenticated report links necessary for iframe integration. Without these credentials, you will not be able to proceed with the integration.

Example Response

The response will include the generated report link.

    {
        "status": "Draft",
        "owner": {
            "name": "testphysician",
            "email": "testphysician@md.ai"
        },
        "reportLink": "https://chat.md.ai/chat/launch-report/clinical?token=8ojevgk4rr"
    }

Note

The owner of this report will now be testphysician and you have successfully created an authenticated report link for them to start dictating.

2. Embed the Iframe

Once you have the generated report link, you can embed it within an iframe in your application. Use the src attribute of the iframe tag to include the report link.

<iframe src="https://chat.md.ai/chat/launch-report/clinical?token=8ojevgk4rr" title="MD.ai Reporting"></iframe>

You can customize the width, height, and other attributes of the iframe to suit your application requirements.

Many of our customers have added a button within their worklists that launches both their image viewer and the MD.ai reporting interface side by side, streamlining the workflow and improving user efficiency.

Here is an example of the reporting system integrated within MD.ai's DICOM viewer and annotation platform as an iframe -