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 with various applications and workflows.
This API works both for launching new reports as well as retrieving existing reports, which can be useful to check for their status (draft, final etc).
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 that you have this identifier before proceeding.
API
Request
Method: POST
API endpoint: https://chat.md.ai/api/report/launch/clinical
- (For Australia: https://au.md.ai/api/report/launch/clinical)
Request Header
Generating MD.ai access tokens
The MD.ai access token can be generated by logging in to chat.md.ai,
clicking on your user avatar in 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
-
clinicalInfo: A dictionary object that stores the clinical information/tags required for report creation that are related to the exam/study. The list of supported tags is given below (required):
-
reportingApp: A dictionary object that stores parameters related to configuring the MD.ai reporting application such as defining the format in which the final report needs to be sent back (eg. HL7) or setting the speech-to-text and UI language. The list of parameters is given below (required).
If you want to sync and open new reports in the same or already opened reporting window on going to a new study in your application/worklist, please refer to the integration guide here.
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 en-US
(US English). For a full list of supported languages please refer to the list
here.
-
response: A dictionary object that specifies the type of output to be returned by the API, whether it's just the encrypted report URL, the QR code image URL, or both. It also includes options to control the size and mode of the QR code. (required)
-
userInfo: A dictionary object used to assign reports to a specific user. By default reports are assigned to the user making the API call based on the access token used, except for iframe integrations where this tag is required.(optional, but required for iframe integration)
-
lazyLaunch: A boolean value that determines when the report is actually created and assigned. (optional)
-
dicomSR: A dictionary object that contains the base64 encoded representation of the DICOM SR file to be imported as the report. The clinical information will be read from the DICOM SR and added to the respective locations. In case both
clinicalInfo
anddicomSR
are provided in the API call, then values from theclinicalInfo
will take precendence. (optional) -
keyImages: A list of dictionary objects that contains key images to be attached to the report. (optional)
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.
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.
-
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
orall
was used inresponse
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 withdata:image/png;base64,
followed by the encoded image data.
Example Request
Here is an example of the request body with all the tags described above:
Example Response
-
If the report already exists and is signed/finalized with
response: {"type": “link”}
: -
For
“response”: {"type": “all”}
and“lazyLaunch”: “false”
: -
For
“response”: {"type": "link"}
and“lazyLaunch”: “True”
:
Note that there is no owner
here since we are just generating a link in advance without actually assigning or launching the report.
Supported Languages
MD.ai provides a comprehensive multilingual reporting system. To customize the language in your reports, use the corresponding Code
from the table below when configuring the SpeechLanguage
(for the speech-to-text language) and AppLanguage
(for the UI language) parameters in our report generation API. Alternatively, you can select the preferred language directly from the user settings.
The currently supported languages are listed below, defaulting to en-US
(US English):
Code | Language |
---|---|
de-DE | German |
en-AU | English (Australia) |
en-GB | English (UK) |
en-US | English (US) |
es-ES | Spanish |
fr-FR | French |
id-ID | Indonesian |
it-IT | Italian |
ja-JP | Japanese |
ko-KR | Korean |
nl-NL | Dutch |
pl-PL | Polish |
pt-BR | Portuguese (Brazil) |
ro-RO | Romanian |
zh-CN | Chinese (Simplified) |
zh-Hant | Chinese (Traditional) |