Basic Iframe Integration Guide

This guide provides instructions for embedding RADPAIR within your application using the simplified iframe integration. This integration is designed for new partners who want to get started quickly with minimal complexity.

This guide covers basic, single-author workflows only. For multi-author workflows, advanced event handling, or complex organizational structures, please refer to the Advanced Integration Guide.

Overview

The Basic Integration is designed to:

• Minimize complexity — Reports flow in via HL7 integration, then open them by MRN and accession number

• Use industry-standard identifiers — MRN and accession number ensure report uniqueness (no internal report IDs needed)

• Handle user management internally — RADPAIR manages user metadata, roles, and authentication

• Provide essential status updates — Five core events: opened, closed, saved, discarded, and signed

Integration Workflow (Summary)

1

HL7 Integration (Handled by Interoperability Partner)

Reports are created and pre-cached via HL7/DICOM before users need them.

2

Embed Iframe

Add RADPAIR iframe to your application to render the reader UI.

3

Authenticate

• Wait for the app_ready event from the iframe.

• Send the access token.

• Wait for sign_in_successful.

4

Open Report

Send the MRN, accession number and site id to open the pre-cached report in the iframe.

5

Listen for Events

Handle core reporting events (opened, saved, signed, discarded, closed).

---

Environments & URLs

RADPAIR operates separate environments with independent databases. API keys, users, and reports are not shared across environments. Use the URLs that match the environment your organization is provisioned on.

Environment	API URL	Iframe URL
US Production	https://api-radpair.com	https://external.radpair.com
EU Production	https://api-eu.radpair.com	https://eu.radpair.com
Staging	https://api-staging.radpair.com	https://staging.radpair.com

Step 1: HL7 Integration (Handled by Interoperability Partner)

Report data flows into RADPAIR through our HL7/DICOM interoperability partner. This integration handles the creation and pre-caching of reports before users access them, ensuring instant load times and proper metadata association.

You do not need to implement this step directly. Your RADPAIR representative will coordinate the HL7 integration setup with your interoperability partner.

Report Delivery

When reports are signed, RADPAIR sends report events to the interoperability partner, who transforms them into HL7 ORU (Observation Result) messages for delivery to your downstream systems (PACS, EMR). This includes support for:

• Standard reports — Delivered upon signature (or after recall window if enabled)

• Linked reports — Multiple studies can be linked to a single report; when signed, events are sent for all linked studies

Data Flow Overview

Endpoint:

POST  https://api.radpair.com/integrations/v2/reports/create

Headers:

Content-Type: application/json
Authorization: Bearer <your-api-key>

Request Body:

{
  "mrn": "MRN123456",
  "accession_number": "ACC789012",
  "site_id": "site_east_01",
  "metadata": {
    "studyDescription": "CT Chest with Contrast",
    "modality": "CT",
    "patient_age": "65",
    "patient_gender": "M",
    "clinical_notes": "Shortness of breath"
  }
}

Required Fields:

Field	Type	Description
mrn	string	Medical Record Number — patient identifier
accession_number	string	Accession number — unique study identifier
site_id	string	Site identifier — used in multi-site organizations to ensure the report is routed to the correct site

Together, MRN and accession number ensure report uniqueness within a site. For multi-site organizations, use the site_id parameter to specify which site the report belongs to.

Optional Metadata Fields

Field	Type	Description
studyDescription	string	Description of the imaging study
clinical_notes	string	Clinical history or reason for exam
laterality	string	Side of body (e.g., "Left", "Right", "Bilateral")
views	string	Imaging views obtained
comparison	string	Prior studies available for comparison
symptom	string	Patient's presenting symptoms
modality	string	Imaging modality (e.g., "CT", "MR", "XR", "US")
contrast	string	Contrast administration details
patient_age	string	Patient's age
patient_gender	string	Patient's gender
pre_findings	string	DICOM SR data or AI-detected findings
findings	string	Pre-populated findings text

---

Organization Hierarchy in RADPAIR

RADPAIR uses a parent-child organization structure to support multi-site deployments. This is particularly important for healthcare systems with multiple facilities that may have different EMR/HIS systems.

┌─────────────────────────────────────────────────────────┐
│  Parent Organization (API Key Holder)                   │
│  "Regional Health System"                               │
│                                                         │
│  ┌────────────────────┐  ┌────────────────────┐         │
│  │  Sub-Organization  │  │  Sub-Organization  │         │
│  │  "East Campus"     │  │  "West Campus"     │  ...    │
│  │  site_id:          │  │  site_id:          │         │
│  │  "SITE_EAST_01"    │  │  "SITE_WEST_01"    │         │
│  └────────────────────┘  └────────────────────┘         │
└─────────────────────────────────────────────────────────┘

Site ID Purpose and Requirements

The site_id field serves as a critical identifier that:

• Maps to HL7 MSH.4 field — Ensures consistency between your HIS/EMR and RADPAIR

• Ensures report uniqueness — Prevents duplicate MRN+Accession combinations across sites

• Routes reports correctly — Directs reports to the appropriate sub-organization

Required Setup: A parent organization (the one with the API key) must have at least one sub-organization created in RADPAIR. Each sub-organization's name must match the site_id value you'll use in API calls.

Multi-Site Example

Consider a regional health system with multiple campuses, each running different EMR systems:

Parent Organization: Regional Health System API Key: Issued to parent organization Sub-Organizations:

• East Campus (site_id: EAST_MAIN_CAMPUS)

• West Campus (site_id: WEST_SATELLITE)

• Downtown Clinic (site_id: DOWNTOWN_URGENT)

When sending reports via HL7 integration:

{
  "mrn": "MRN123456",
  "accession_number": "ACC789012",
  "site_id": "EAST_MAIN_CAMPUS",  // Matches HL7 MSH.4 field
  "metadata": {
    "studyDescription": "CT Chest with Contrast",
    "modality": "CT"
  }
}

This ensures that even if two different campuses have a patient with the same MRN and coincidentally the same accession number, they'll be treated as separate, unique reports.

Setting Up Sub-Organizations

1

Step 1

Navigate to your parent organization's settings in RADPAIR.

2

Step 2

Create sub-organizations for each site that will send reports.

3

Step 3

Name each sub-organization exactly as it appears in your HL7 MSH.4 field.

4

Step 4

Use these same values as the site_id in all API calls.

5

Step 5

Required Org Setting: Enable Sub-Organization Report Access

For users to access reports routed to sub-organizations via `site_id`, an admin must enable "Enable Sub-Organization Report Access" in the parent org's Integration settings.

Navigate to Org Settings → Integration → Enable Sub-Organization Report Access and toggle it on.

Single-Site Organizations: If you're operating a single facility, you can use your parent organization directly as the site_id, or optionally create a sub-organization with an identifier like "MAIN" or your facility code.

---

Step 2: Embed the Iframe

Add the RADPAIR iframe to your application:

<iframe
  id="radpair-iframe"
  allow="microphone; hid"
  credentialless
  src="https://external.radpair.com?headless=true"
  style="width: 100%; height: 600px; border: none;"
></iframe>

Iframe Attributes

Attribute	Purpose
allow="microphone; hid"	Required for dictation and hardware devices (e.g., SpeechMike)
credentialless	Isolates session storage to prevent conflicts with multiple instances
?headless=true	Hides RADPAIR navigation UI for embedded use

Advanced Workflow Control: The Basic Integration covers standard report opening and event listening. For fine-grained control of the RADPAIR interface—such as programmatically controlling dictation recording, signing reports, managing report state (save/discard/close), adding addendums, customizing UI visibility, or configuring notifications—see Further Iframe Interactions during Reporting in the Advanced Integration Guide.

---

Step 3: Authentication

Obtaining an API Key

1. Navigate to your organization's settings page in RADPAIR

2. Click the options menu (⋮) and select "API Keys"

3. Click "Create New API Key"

4. Copy and securely store the generated key — it will only be shown once

Creating an Access Token

Endpoint:

POST https://api.radpair.com/integrations/auth/token

Headers:

Content-Type: application/json
Authorization: Bearer <your-api-key>

Request Body:

{
  "user_email": "[email protected]",
  "first_name": "Jane",
  "last_name": "Smith"
}

Parameter	Type	Required	Description
user_email	string	✅	Email of the user
first_name	string	❌	User's first name
last_name	string	❌	User's last name

Response:

{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}

Access tokens expire after 24 hours.

Authenticating the Iframe

const iframe = document.getElementById('radpair-iframe');
const RADPAIR_URL = 'https://external.radpair.com';

// Wait for app_ready, then authenticate
window.addEventListener('message', (event) => {
  if (event.origin !== RADPAIR_URL) return;

  if (event.data?.event === 'app_ready') {
    iframe.contentWindow.postMessage(
      { authentication: `Bearer ${accessToken}` },
      RADPAIR_URL
    );
  }

  if (event.data?.event === 'sign_in_successful') {
    console.log('Ready to open reports');
  }
});

---

Step 4: Open Reports

Once authenticated, open a report by sending the MRN, accession number, and site id. If the report does not already exist in RADPAIR, it will be created automatically — making this an upsert operation.

You can also include optional metadata fields to provide clinical context, just as you would with the report creation endpoint. If the report already exists, the metadata will be updated with the provided values.

iframe.postMessage({
  open_report: {
    mrn: 'MRN123456',
    accession_number: 'ACC789012',
    site_id: 'site_east_01',
    metadata: { // Optional: Metadata can be sent in the open as well. 
      studyDescription: 'MR Brain without Contrast',
      modality: 'MR',
      clinical_notes: 'Headache, rule out mass',
      patient_age: '42',
      patient_gender: 'F'
    }
  }
}, RADPAIR_URL);

Example: Open with Metadata

Field	Type	Description
studyDescription	string	Description of the imaging study
clinical_notes	string	Clinical history or reason for exam
laterality	string	Side of body (e.g., "Left", "Right", "Bilateral")
views	string	Imaging views obtained
comparison	string	Prior studies available for comparison
symptom	string	Patient's presenting symptoms
modality	string	Imaging modality (e.g., "CT", "MR", "XR", "US")
contrast	string	Contrast administration details
patient_age	string	Patient's age
patient_gender	string	Patient's gender
pre_findings	string	DICOM SR data or AI-detected findings
findings	string	Pre-populated findings text

The metadata object supports the same fields as the report creation endpoint:

Optional Metadata Fields

Ensuring Report Uniqueness: MRN and accession number together uniquely identify the report within a site. For multi-site organizations where these identifiers may overlap, you can provide the site_id parameter to specify which site the report belongs to.

Upsert Behavior: If a report matching the given MRN, accession number, and site ID already exists, it will be opened. If no matching report exists, one will be created automatically with the provided metadata.

Required Fields:

Field	Type	Description
mrn	string	Medical Record Number — patient identifier
accession_number	string	Accession number — unique study identifier
site_id	string	Site identifier — used in multi-site organizations to ensure the report is routed to the correct site

Example:

iframe.postMessage({
  open_report: {
    mrn: 'MRN123456',
    accession_number: 'ACC789012',
    site_id: 'site_east_01',
    metadata: {
      studyDescription: 'CT Chest with Contrast',
      modality: 'CT',
      patient_age: '65',
      patient_gender: 'M',
      clinical_notes: 'Shortness of breath'
    }
  }
}, RADPAIR_URL);

Closing Reports

To close the currently open report:

iframe.postMessage({ close_report: true }, RADPAIR_URL);

---

Step 4a: Linking Multiple Reports (Coming Soon)

RADPAIR supports linking multiple studies from the same patient into a single combined report. This is useful when a radiologist needs to read and report on multiple related studies together (e.g., multiple body parts from the same examination, or comparison studies).

How Report Linking Works

To link multiple reports, send the same MRN with multiple accession numbers. RADPAIR will automatically link these studies together in the system, allowing the radiologist to view and report on them as a unified report.

As with single reports, this is an upsert operation — any reports that do not already exist will be created automatically. You can provide per-report metadata using the metadata_by_accession field.

Persistent Linking: Once reports are linked, opening any individual report in the group will always open the full combined report. Linked reports cannot be unlinked by re-opening a single accession number.

Opening and Linking Multiple Reports

iframe.postMessage({
  open_report: {
    mrn: 'MRN123456',
    site_id: 'site_east_01',
    accession_numbers: ['ACC001', 'ACC002', 'ACC003'],
  }
}, RADPAIR_URL);

Required Fields for Linked Reports:

Field	Type	Description
mrn	string	Medical Record Number — must be the same for all linked reports
accession_numbers	string[]	Array of accession numbers to link together
site_id	string	Site identifier — used in multi-site organizations to ensure the report is routed to the correct site

Optional Fields:

Field	Type	Description
metadata_by_accession	object	Per-report metadata keyed by accession number. Each value supports the same metadata fields as the report creation endpoint (see Optional Metadata Fields in Step 4).

Important: All reports being linked must belong to the same patient (same MRN). If any of the reports do not already exist, they will be created automatically. When the radiologist signs the combined report, events will be sent for all linked accession numbers.

Example: Linking Three Studies

// Link chest, abdomen, and pelvis CT studies for the same patient
iframe.postMessage({
  open_report: {
    mrn: 'MRN123456',
    site_id: 'site_east_01',
    accession_numbers: ['ACC_CHEST_001', 'ACC_ABDOMEN_002', 'ACC_PELVIS_003'],
    metadata_by_accession: {
      ACC_CHEST_001: {
        studyDescription: 'CT Chest with Contrast',
        modality: 'CT',
        clinical_notes: 'Evaluate lung nodule'
      },
      ACC_ABDOMEN_002: {
        studyDescription: 'CT Abdomen with Contrast',
        modality: 'CT'
      },
      ACC_PELVIS_003: {
        studyDescription: 'CT Pelvis with Contrast',
        modality: 'CT'
      }
    }
  }
}, RADPAIR_URL);

Events for Linked Reports

When a linked report is signed, RADPAIR will send separate report.signed events for each linked accession number. Your application should handle these events individually:

// When signing a linked report with 3 accessions, you'll receive 3 events:
{
  "type": "reporting_event",
  "event": "report.signed",
  "payload": {
    "mrn": "MRN123456",
    "site_id": "site_east_01",
    "accession_number": "ACC_CHEST_001",
    "report_status": "signed",
    ...
  }
}
{
  "type": "reporting_event",
  "event": "report.signed",
  "payload": {
    "mrn": "MRN123456",
    "site_id": "site_east_01",
    "accession_number": "ACC_ABDOMEN_002",
    "report_status": "signed",
    ...
  }
}
{
  "type": "reporting_event",
  "event": "report.signed",
  "payload": {
    "mrn": "MRN123456",
    "site_id": "site_east_01",
    "accession_number": "ACC_PELVIS_003",
    "report_status": "signed",
    ...
  }
}

---

Step 5: Listen for Events

RADPAIR sends events to notify your application of report state changes. For basic integrations, you only need to handle five core events.

Core Events

Event	Description	When It Fires
report.opened	Report was opened	User opens a report
report.closed	Report was closed	User closes or navigates away from report
report.saved	Report saved as draft	User saves work in progress
report.discarded_completely	Report was discarded	User discards the report (unassigns it, making it available for others)
report.signed	Report was signed	User signs the report (triggers downstream delivery)

Note on report.published: A report.published event also exists, but you can ignore it — report delivery to downstream systems (PACS, EMR) is handled automatically by our HL7 interoperability partner.

Note on Report Recall: If Report Recall is enabled, you will receive a report.signed event at the beginning of the recall period, and then again when the recall window has elapsed (or if the user clicks "Sign Now"). If a user recalls a report during that time, you will receive a report.opened event with a report status of draft.

Event Listener Example

window.addEventListener('message', (event) => {
  if (event.origin !== 'https://external.radpair.com') return;

  if (event.data?.type === 'reporting_event') {
    const { event: eventType, payload } = event.data;

    switch (eventType) {
      case 'report.opened':
        console.log('Report opened:', payload.mrn, payload.accession_number);
        break;

      case 'report.closed':
        console.log('Report closed:', payload.mrn, payload.accession_number);
        break;

      case 'report.saved':
        console.log('Report saved (draft):', payload.mrn, payload.accession_number);
        console.log('Status:', payload.report_status);
        break;

      case 'report.discarded_completely':
        console.log('Report discarded:', payload.mrn, payload.accession_number);
        break;

      case 'report.signed':
        console.log('Report signed:', payload.mrn, payload.accession_number);
        console.log('Report status:', payload.report_status);
        handleSignedReport(payload);
        break;
    }
  }
});

function handleSignedReport(payload) {
  // Update your UI or internal state
  console.log('Report signed by:', payload.user_info?.full_name);
  console.log('Status:', payload.report_status); // 'signed', 'preliminary', or 'addendum'
}

Event Payload Structure

All events include both MRN, accession number and site id for identification:

{
  "type": "reporting_event",
  "event": "report.signed",
  "payload": {
    "timestamp": 1743518340903,
    "mrn": "MRN123456",
    "site_id": "site_east_01",
    "accession_number": "ACC789012",
    "report_status": "signed",
    "user_info": {
      "email": "[email protected]",
      "full_name": "Jane Doe"
    }
  }
}

Key Payload Fields:

Field	Description
mrn	The Medical Record Number
accession_number	The accession number
report_status	Signature type: preliminary, signed, or addendum
user_info	Information about the user who signed
timestamp	Unix timestamp of the event
site_id	The site id

Report.signed — Sign Type Values

The report.signed event fires for all signing actions. Use payload.data.sign_context.sign_type to determine which type of signing occurred:

sign_type Value	Description	Resulting report_status
sign	Final signing	signed
sign_prelim	Preliminary signing	prelim_signed
sign_addendum	Addendum final signing	addendum_signed
sign_addendum_prelim	Addendum preliminary signing	addendum_prelim_signed

case 'report.signed':
  const signType = payload.data.sign_context.sign_type;
  if (signType === 'sign') {
    // Final signature
  } else if (signType === 'sign_prelim') {
    // Preliminary signature
  } else if (signType === 'sign_addendum') {
    // Addendum final signature
  } else if (signType === 'sign_addendum_prelim') {
    // Addendum preliminary signature
  }
  break;

Events return the same mrn , accession_number and site_id from the HL7 integration. You do not need to track internal report IDs.

---

Complete Integration Example

const RADPAIR_URL = 'https://external.radpair.com';
let iframe;
let isAuthenticated = false;

// Initialize
function initRadpair() {
  iframe = document.getElementById('radpair-iframe');
  window.addEventListener('message', handleMessage);
}

// Handle all messages
function handleMessage(event) {
  if (event.origin !== RADPAIR_URL) return;
  const { data } = event;

  // Authentication flow
  if (data.event === 'app_ready') {
    authenticateUser();
  }

  if (data.event === 'sign_in_successful') {
    isAuthenticated = true;
    console.log('Ready to open reports');
  }

  // Report events
  if (data.type === 'reporting_event') {
    handleReportEvent(data.event, data.payload);
  }
}

// Authenticate
async function authenticateUser() {
  const token = await getAccessToken(); // Your backend call
  iframe.contentWindow.postMessage(
    { authentication: `Bearer ${token}` },
    RADPAIR_URL
  );
}

// Open a single pre-cached report
function openReport(mrn, siteId, accessionNumber) {
  if (!isAuthenticated) {
    console.error('Not authenticated');
    return;
  }

  iframe.contentWindow.postMessage({
    open_report: {
      mrn: mrn,
      site_id: siteId,
      accession_number: accessionNumber
    }
  }, RADPAIR_URL);
}

// Open and link multiple reports for the same patient
function openLinkedReports(mrn, siteId, accessionNumbers) {
  if (!isAuthenticated) {
    console.error('Not authenticated');
    return;
  }

  iframe.contentWindow.postMessage({
    open_report: {
      mrn: mrn,
      site_id: siteId,
      accession_numbers: accessionNumbers
    }
  }, RADPAIR_URL);
}

// Handle report events
function handleReportEvent(eventType, payload) {
  switch (eventType) {
    case 'report.opened':
      updateUI('Report opened');
      break;
    case 'report.saved':
      updateUI('Draft saved');
      break;
    case 'report.signed':
      handleSignedReport(payload);
      updateUI('Report signed');
      break;
    case 'report.discarded_completely':
      updateUI('Report discarded');
      break;
    case 'report.closed':
      updateUI('Report closed');
      break;
  }
}

// Handle signed report
function handleSignedReport(payload) {
  console.log('Report signed:', payload.mrn, payload.site_id, payload.accession_number);
  console.log('Signed by:', payload.user_info?.full_name);
  console.log('Status:', payload.report_status);
  // Report delivery to PACS/EMR is handled by HL7 interoperability partner
}

document.addEventListener('DOMContentLoaded', initRadpair);

---

Report Status Values

Events include a report_status field indicating the current state:

Status	Description
unread	Report is unread
draft	Report is being worked on, not yet signed
prelim_signed	Preliminary read (resident/trainee signature)
signed	Final signature by attending radiologist
addendum_signed	Addendum added to a signed report
addendum_prelim_signed	Prelim Addendum added to a signed report

---

Additional Features

Critical Results Labeling

Critical Results Labeling allows radiologists to flag reports with critical findings directly from the reporting interface. When enabled, a dropdown appears in the report sidebar where users can select from organization-defined critical result options before or during signing.

Enabling Critical Results Labeling

This feature requires integration to be enabled. To configure it:

1

Navigate to the settings

Navigate to Org Settings → General → Critical Results Labeling.

2

Enable the feature

Toggle the feature on.

3

Add critical result options

Add one or more critical result options, each with:

• Name — Display label shown to users (e.g., "Stroke Alert", "Pulmonary Embolism")

• Value — Unique identifier included in event payloads (e.g., "stroke", "pe")

Option names and values must each be unique within the organization. You can define options before enabling the feature.

User Experience

When enabled, a Critical Result accordion appears in the report sidebar with a warning icon. The radiologist can:

• Select a critical result option from the dropdown before or at the time of signing

• Clear the selection if no critical finding applies

• See both the display name and value for each option

The selected critical result is saved to the report immediately upon selection.

Critical Result in Event Payloads

When a report has a critical result selected, the critical_result field is included in all event payloads (iframe events and webhooks). If no critical result is selected, the field is null.

Iframe event payload example:

{
  "type": "reporting_event",
  "event": "report.signed",
  "payload": {
    "timestamp": 1743518340903,
    "mrn": "MRN123456",
    "site_id": "site_east_01",
    "accession_number": "ACC789012",
    "report_status": "signed",
    "critical_result": {
      "name": "Stroke Alert",
      "value": "stroke"
    },
    "user_info": {
      "email": "[email protected]",
      "full_name": "Jane Doe"
    }
  }
}

Critical Result Field:

Field	Type	Description
critical_result	object / null	The selected critical result, or null if none
critical_result.name	string	Display name of the critical result option
critical_result.value	string	Unique identifier for the critical result option

The critical_result field appears consistently across all event types — including report.signed, report.saved, and report.updated — as well as in webhook payloads and public API responses.

Handling Critical Results in Your Integration

case 'report.signed':
  const { critical_result } = payload;
  if (critical_result) {
    console.log('CRITICAL FINDING:', critical_result.name);
    console.log('Value:', critical_result.value);
    // Trigger your critical result workflow (e.g., alerts, escalation)
    handleCriticalResult(critical_result);
  }
  break;

Troubleshooting

Use the expandable items below to view common troubleshooting scenarios.

"App not ready" errors

Wait for the app_ready event before sending authentication.

"Not authenticated" errors

• Verify the access token is valid (tokens expire after 24 hours)

• Ensure you received sign_in_successful before opening reports

Report not opening

• Verify the report exists (was received via HL7 integration)

• Check that both MRN and accession number match exactly

• Ensure the user belongs to the organization where the report was created

• In rare cases with complex multi-site organizations, verify the org_path is correct

• For linked reports, ensure all accession numbers have been pre-cached and belong to the same MRN

Events not received

• Confirm event listener is checking the correct origin

• Ensure iframe is loaded before adding the listener

Linked reports not working

• Verify all accession numbers belong to the same patient (same MRN)

• Ensure all studies have been pre-cached via HL7 integration

• Check that you're using the accession_numbers array (plural) for linked reports

---

Support

For integration support, contact your RADPAIR representative or email [email protected].