Skip to content

Report Generation API

The Report Generation API is designed to facilitate the creation of secure, encrypted links and optionally QR codes for accessing clinical reports within the MD.ai reporting application. By sending a POST request with the necessary clinical tags, users can quickly generate the required report links. Additionally, a QR code image can also be generated for easy sharing and scanning. It is designed to be straightforward and flexible, enabling seamless integration into various applications and workflows.

To integrate and generate new reports using our API, you will need a SiteID specific to your organization that will be provided to you by MD.ai. Ensure you have this identifier before proceeding.

Method: POST

API endpoint: https://chat.md.ai/api/report/launch/clinical

Request Header

    Content-Type: application/json
    x-access-token: YOUR_MDAI_ACESS_TOKEN

Generating MD.ai access tokens

The MD.ai access token can be generated by logging in to chat.md.ai, clicking your user avatar on the top right corner, and going to User Settings -> Access tokens. Make sure to add this token to the header as x-access-token for authentication, otherwise the request will fail.

Request Body

  • tags: A dictionary object to store all clinical info for the report to be created. (required). The list of supported tags is given below -
    SiteID: Unique identifier for your organization (will be provided by MD.ai)
    PatientMRN: Unique patient identifier or Patient MRN
    Accession: Unique report identifier or Accession Number
    PatientName: Name of the patient
    PatientBirthDate: DOB of the patient
    PatientAge: Age of the patient
    PatientSex: Sex of the patient
    Modality: Modality of the study eg. CT, MR etc
    BodyPartExamined: Body part of interest for the report
    StudyDescription: Brief description of the study
    StudyDate: Date when the study was performed
    StudyTime: Time of the study
    StudyInstanceUID: Study UID of the imaging study related to the report
    ReasonForExam: Reason for ordering the exam or patient history/symptoms.
    ReturnFormat: Format to return the report into your system. HL7 is supported.
    SpeechLanguage: Language used for dictation and speech recognition. Ensures the speech-to-text system processes spoken inputs in the correct language.
    AppLanguage: Language for UI localization. The application interface will render in the specified langauge.
    KeyFindings: Draft report or text that you want to pre-populate the report with.

Language Settings for Non-English Usage

Many of our AI features rely on the language settings, so for non-English usage the AppLanguage and SpeechLanguage tags in the request are required. If not provided, both tags will default to English.

Currently supported languages include: en (English), es (Spanish), fr (French), ja (Japanese), de (German), nl (Dutch), ko (Korean), pl (Polish), ro (Romanian), pt (Portugese - Brazil), zh-CN (Chinese Simplified) and zh-Hant (Chinese Traditional)

  • result: Specifies the type of output to be returned by the API. (required)
    link: Returns only the encrypted report URL.
    qrcode: Returns only the QR code image URL.
    all: Returns both the encrypted report URL and the QR code image URL 
  • lazyLaunch: A boolean value that controls when the report is actually created and assigned. (optional)
    false: The report is created, assigned, and saved in the backend immediately when the API request is made. (default)
    true: The API will generate and return a link to the report and/or QR code without immediately creating the actual report in the backend. The report will only be created, assigned, and saved when the generated link is accessed for the first time. This can be useful for scenarios where you want to defer the creation of the report until it is actually needed. 
  • qrCodeSize: If qrcode or all was used in result to return a QR code, use this parameter to control the size of the QR code returned. (optional)
    standard: The width of the QR code will be 400 pixels. (default)
    small: The width of the QR code will be 80 pixels.
  • qrCodeMode: If qrcode or all was used in result to return a QR code, use this parameter to control the the appearance of the QR code. (optional)
    light: Suitable for light mode/white backgrounds. (default)
    dark: Suitable for dark mode/black backgrounds.

HL7 Integration

For receiving reports back as HL7 or for any custom integration, we’ll work with your team to configure the system/endpoint details. This workflow will only be triggered after the report is signed/finalized by the user.

Example request

Here is an example for the reqeust body with all the tags -

    {
        "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.",
            "SpeechLanguage": "en",
            "AppLanguage": "en"
        },
        "result": "all",
        "lazyLaunch": true,
        "qrCodeSize": "mini",
        "qrCodeMode": "dark",
    }

Response

The response for this POST request will be a JSON object that contains the following keys -

  • status: Indicates the current status of the report, allowing users to determine whether the report is finalized, still being edited, or pending creation.
    Final: The report is finalized and signed. No further changes can be made.
    Draft: The report is still being edited and has not been signed or finalized.
    PreLaunch: This special status is returned when `lazyLaunch` is set to `true`. It indicates that the report has not yet been created or assigned; only the link has been generated.
  • owner: Contains information about the owner of the report - name and email.
  • reportLink: Contains the URL for the generated report based on the tags provided. This link is encrypted and does not display the actual tags that were sent, to ensure secure access to the report.
  • reportQrCode: If qrcode or all was used in result to return a QR code, this field contains a base64-encoded string representing the QR code image to access the report. The base64 string starts with data:image/png;base64 followed by the encoded image data.
Example response
  • If the report already exists and is signed/finalized with “result”: “link”:
    {
        "status": "Final",
        "owner": {
            "name": "Test User",
            "email": "test-user@md.ai"
        },
        "reportLink": "https://chat.md.ai/chat/launch-report/clinical?token=8ojevgk4rr"
    }
  • For “result”: “all” and “lazyLaunch”: “false”:
    {
        "status": "Draft",
        "owner": {
            "name": "Test User",
            "email": "test-user@md.ai"
        },
        "reportLink": "https://chat.md.ai/chat/launch-report/clinical?token=8ojevgk4rr",
        "reportQRCode": "data:image/png;base64,iVBOR"
    }
  • For “result”: “link” and “lazyLaunch”: “True”:
    {
        "status": "PreLaunch",
        "owner": {},
        "reportLink": "https://chat.md.ai/chat/launch-report/clinical?token=8ojevgk4rr"
    }

Note that there is no owner here since we are just generating a link in advance without actually assigning or launching the report.