Implementation Guide: Transcribe specialist referral calls and auto-populate referral forms

Hardware Procurement

Software Procurement

Prerequisites

• Signed Business Associate Agreement (BAA) with every vendor in the pipeline: Dialpad, HealOS (or OraCore for dental), Microsoft Azure (if using custom pipeline), and any EHR cloud vendor. No PHI may be processed until all BAAs are executed.
• Current EHR or dental PMS system with API access enabled: Epic (App Orchard enrollment), athenahealth (Marketplace API credentials), eClinicalWorks (API access request), NextGen (FHIR API setup), Dentrix (API Exchange registration), or Open Dental (REST API enabled in Program Properties).
• Stable internet connection: minimum 25 Mbps download / 10 Mbps upload for practices with 3+ concurrent VoIP users. Latency must be under 50ms to nearest cloud region. Verify with speed tests at multiple times of day.
• QoS-capable network switch and router already deployed or included in hardware procurement. VoIP VLAN must be configured to prioritize SIP/RTP traffic (DSCP EF marking for voice, AF41 for signaling).
• All referral coordinator and provider workstations running Windows 10/11 (22H2+) or macOS 13+ with Chrome 110+ or Edge 110+ installed. Minimum 8GB RAM (16GB preferred). Existing antivirus/EDR must whitelist Dialpad desktop app and HealOS browser extension.
• Practice administrator with EHR superuser credentials available for integration configuration, referral form template access, and FHIR/HL7 endpoint provisioning.
• Legal review of state-specific call recording consent laws completed. For two-party consent states (CA, FL, IL, MD, WA, PA, CT, NH, MT, MA), automated consent announcement script approved by practice legal counsel.
• Patient consent workflow defined and approved: consent language for call recording, opt-out procedures, documentation method (EHR flag, consent form scan, or electronic signature).
• Inventory of all current referral form fields per specialty (e.g., orthopedics, cardiology, gastroenterology, oral surgery). This mapping is required to configure the NLP extraction templates. Collect 10–20 sample completed referral forms from each high-volume specialty.
• Dedicated project point-of-contact at the practice: referral coordinator lead or office manager with authority to approve workflow changes, schedule training sessions, and sign off on go-live.

Installation Steps

Step 1: Project Kickoff and Workflow Discovery

Conduct a 2-hour on-site or virtual discovery session with the practice's referral coordinator(s), office manager, and at least one provider. Map the current referral call workflow end-to-end: who initiates calls, what information is exchanged, which forms are filled out, which EHR modules are used, and where bottlenecks occur. Document all referral form fields per specialty. Identify the top 5 referral specialties by volume. Collect 10–20 completed sample referral forms. Assess the current phone system (make, model, VoIP provider, recording capabilities). Verify all prerequisites from the checklist.

Step 2: Execute BAAs and Compliance Documentation

Before any technical work begins, ensure all Business Associate Agreements are signed. Create accounts with Dialpad (HIPAA plan), HealOS, and Microsoft Azure (if applicable). Request BAAs from each vendor's compliance or sales team. Have the practice's HIPAA Privacy Officer or practice owner countersign each BAA. Upload executed BAAs to the Compliancy Group platform (or equivalent compliance tracker). Configure the consent announcement script in the phone system (to be deployed in Step 4). Document the consent workflow: how consent is obtained, recorded, and stored.

Step 3: Network Assessment and QoS Configuration

Assess the practice network for VoIP readiness. Run bandwidth and latency tests. Configure QoS on the network switch and firewall/router to prioritize voice traffic. Create a dedicated VLAN for VoIP endpoints (phones, softphone workstations). Configure DSCP markings: EF (46) for RTP voice media, AF41 (34) for SIP signaling. Ensure the firewall allows Dialpad's required ports and domains.

configure
interface vlan 100
  description VoIP-Referral-Phones
exit

iperf3 -c speedtest.dialpad.com -u -b 1M -t 30
ping -c 100 api.dialpad.com

Step 4: Deploy Dialpad HIPAA-Compliant Phone System

Provision Dialpad accounts for all referral-related staff. Install the Dialpad desktop application on referral coordinator workstations. Configure call recording with automatic consent announcements. Set up call recording retention policies aligned with state medical records laws (typically 7–10 years). Configure Dialpad AI transcription to generate real-time transcripts. Set up a Dialpad API application for programmatic access to call recordings and transcripts (needed for HealOS integration or custom pipeline). Deploy Jabra speakerphones at each referral coordinator desk and pair via USB.

# silent install via Intune/SCCM

# Install Dialpad desktop app (Windows)
# Download from https://dialpad.com/download
# Or deploy via Intune/SCCM with silent install:
DialpadInstaller.exe /S /ALLUSERS

# Install Dialpad desktop app (macOS)
# Download .dmg from https://dialpad.com/download
# Or deploy via Jamf/Mosyle:
sudo installer -pkg /path/to/Dialpad.pkg -target /

Step 5: Deploy HealOS AI Scribe and Referrals Agent (Medical Practices)

Create the practice's HealOS organization account. Add provider and referral coordinator user accounts. Configure the HealOS Referrals Agent module. Connect HealOS to the practice's EHR system using the appropriate integration method (FHIR API, HL7v2 interface, or direct integration if available). Map all referral form fields identified during discovery to HealOS extraction templates. Configure specialty-specific referral templates (e.g., cardiology referral has different required fields than orthopedic referral).

curl -X GET 'https://[ehr-fhir-endpoint]/Patient?name=TestPatient' \
  -H 'Authorization: Bearer [access_token]' \
  -H 'Accept: application/fhir+json'

• If using HL7v2 interface engine (e.g., Mirth Connect): Configure channel: TCP Listener on port 6661
• Source: HealOS outbound HL7 REF message
• Destination: EHR HL7 inbound interface
• Message type: REF^I12 (Patient Referral)

Step 6: Deploy OraCore Scribe (Dental Practices Only — Alternative to Step 5)

For dental practice clients, deploy OraCore Scribe instead of HealOS. Create the practice account, configure PMS integration with Dentrix or Open Dental, and set up referral documentation templates for common dental specialties (oral surgery, endodontics, orthodontics, periodontics).

curl -X GET 'https://[opendental-server]:30222/api/v1/patients?LName=Test' \
  -H 'Authorization: ODFHIR [API_key]'

Step 7: Connect Dialpad Call Recordings to AI Processing Pipeline

Configure the data flow from Dialpad (call capture) to HealOS (AI processing). This is the critical integration that connects the phone system to the referral AI agent. Set up a webhook or scheduled API polling job that sends completed call recordings and transcripts from Dialpad to HealOS for referral entity extraction and form population. For practices using the custom Azure pipeline, configure Dialpad to send recordings to Azure Blob Storage instead.

Option A: Dialpad Webhook to HealOS (Preferred)

Option B: Custom Middleware (Azure Functions) for Practices Needing Transformation

# initialize function app and create HTTP trigger

func init ReferralCallProcessor --python
func new --name DialpadWebhook --template 'HTTP trigger'

curl -X GET 'https://dialpad.com/api/v2/calls/[call_id]/recording' \
  -H 'Authorization: Bearer [dialpad_api_key]' \
  -o call_recording.wav

curl -X GET 'https://dialpad.com/api/v2/calls/[call_id]/transcript' \
  -H 'Authorization: Bearer [dialpad_api_key]'

Option C: Manual Upload Workflow (Simplest, for Pilot Phase)

Step 8: Configure NLP Extraction Templates and Referral Field Mapping

Using the sample referral forms collected during discovery, configure the AI extraction templates that map transcribed call content to specific referral form fields. This is done within HealOS Referrals Agent (or via custom prompts if using Azure OpenAI). Each specialty may have different required fields. Test with 5–10 real historical referral calls (with PHI redacted or using test data) to validate extraction accuracy before going live.

Step 9: Configure EHR/PMS Referral Form Write-Back

Set up the automated or semi-automated write-back from HealOS extracted data to the EHR's referral module. This varies significantly by EHR system. For FHIR-enabled EHRs (Epic, athenahealth), use the ServiceRequest and Patient FHIR resources. For HL7v2-based systems, configure REF^I12 messages. For dental PMS systems with limited APIs, configure a clipboard-paste or screen-scraping integration as a fallback.

curl -X POST 'https://[ehr-fhir-endpoint]/ServiceRequest' \
  -H 'Authorization: Bearer [access_token]' \
  -H 'Content-Type: application/fhir+json' \
  -d '{
    "resourceType": "ServiceRequest",
    "status": "draft",
    "intent": "order",
    "category": [{
      "coding": [{
        "system": "http://snomed.info/sct",
        "code": "3457005",
        "display": "Patient referral"
      }]
    }],
    "code": {
      "coding": [{
        "system": "http://snomed.info/sct",
        "code": "[specialty_snomed_code]",
        "display": "[Specialty Name] referral"
      }]
    },
    "subject": {
      "reference": "Patient/[patient_fhir_id]"
    },
    "requester": {
      "reference": "Practitioner/[referring_provider_fhir_id]"
    },
    "performer": [{
      "reference": "Practitioner/[specialist_fhir_id]"
    }],
    "reasonCode": [{
      "coding": [{
        "system": "http://hl7.org/fhir/sid/icd-10-cm",
        "code": "[icd10_code]",
        "display": "[diagnosis_description]"
      }]
    }],
    "note": [{
      "text": "[clinical_summary_and_reason_for_referral]"
    }],
    "priority": "[routine|urgent|stat]"
  }'

MSH|^~\&|HEALOS|REFERRAL_AI|EHR|PRACTICE|[timestamp]||REF^I12|[msg_id]|P|2.5
PID|1||[MRN]^^^PRACTICE^MR||[LastName]^[FirstName]||[DOB]|[Sex]
IN1|1|[InsurancePlanID]|[InsuranceCarrier]|||||||[GroupNumber]|||||||[MemberID]
PRD|RP|[ReferringProvider]^[FirstName]||||||[NPI]
PRD|RT|[ReceivingSpecialist]^[FirstName]||||||[NPI]
DG1|1||[ICD10Code]^[DiagnosisDescription]^I10
RF1|[Priority]|[ReferralReason]||[RequestedDate]
NTE|1||[ClinicalSummary]

curl -X POST 'https://api.dentrix.com/v1/patients/[patient_id]/referrals' \
  -H 'Authorization: Bearer [dentrix_api_key]' \
  -H 'Content-Type: application/json' \
  -d '{
    "referral_type": "outgoing",
    "specialist_name": "[specialist_name]",
    "specialty": "[specialty]",
    "reason": "[reason_for_referral]",
    "notes": "[clinical_summary]",
    "urgency": "[routine|urgent]",
    "tooth_numbers": ["[tooth_1]", "[tooth_2]"]
  }'

Step 10: Configure Call Recording Consent Workflow

Implement the automated and documented consent workflow for call recording. This is legally and regulatory mandatory. Configure Dialpad to play a consent announcement at the start of every outbound and inbound call on referral lines. For two-party consent states, configure explicit acknowledgment. Set up consent documentation in the EHR. Create an opt-out workflow for callers who decline recording.

curl -X POST 'https://[ehr-fhir-endpoint]/Consent' \
  -H 'Authorization: Bearer [access_token]' \
  -H 'Content-Type: application/fhir+json' \
  -d '{
    "resourceType": "Consent",
    "status": "active",
    "scope": {
      "coding": [{
        "system": "http://terminology.hl7.org/CodeSystem/consentscope",
        "code": "patient-privacy"
      }]
    },
    "patient": {"reference": "Patient/[patient_id]"},
    "dateTime": "[timestamp]",
    "policy": [{
      "uri": "https://[practice-domain]/policies/ai-recording-consent"
    }],
    "provision": {
      "type": "permit",
      "purpose": [{
        "system": "http://terminology.hl7.org/CodeSystem/v3-ActReason",
        "code": "TREAT"
      }]
    }
  }'

Step 11: Pilot Deployment and Accuracy Validation

Deploy the complete pipeline for 1–2 referral coordinators handling the highest-volume specialty referrals. Run in 'review mode' where every auto-populated referral form is reviewed and approved by the coordinator before submission. Track accuracy metrics for 2 weeks. Conduct daily check-ins during the first week and twice-weekly check-ins during the second week.

# Accuracy tracking formula:
# Field Accuracy = (Correctly Extracted Fields) / (Total Fields) × 100
# Target: >90% overall, >95% for patient name and DOB

Step 12: Full Deployment and Staff Training

After pilot validation confirms >90% extraction accuracy and positive coordinator feedback, roll out to all referral coordinators and configure auto-processing for all referral call lines. Conduct a 1-hour training session for all referral staff covering: the new workflow, how to review auto-populated forms, how to correct extraction errors, how to handle opt-out callers, and how to escalate technical issues. Provide a printed quick-reference card for each workstation.

Full Rollout Steps and Training Agenda

Custom AI Components

Referral Call Entity Extraction Prompt

Type: prompt

A structured GPT-5.4 prompt template used in the Azure OpenAI custom pipeline (Alternative Approach B) or as supplementary extraction logic when HealOS's built-in extraction needs enhancement. This prompt takes a raw call transcript as input and outputs a structured JSON object containing all referral form fields. It handles speaker diarization context, medical terminology, insurance nomenclature, and ambiguous or missing information.

Implementation:

System Prompt for Azure OpenAI GPT-5.4 (Referral Entity Extraction)

You are a HIPAA-compliant medical referral data extraction agent. You analyze transcripts of specialist referral phone calls between medical/dental practice staff and extract structured data to populate referral forms.

Instructions:

Output JSON Schema:

{
  "extraction_metadata": {
    "call_duration_mentioned": "string or null",
    "speakers_identified": ["string"],
    "overall_confidence": "high|medium|low",
    "extraction_timestamp": "ISO8601"
  },
  "patient": {
    "full_name": {"value": "string or null", "confidence": "high|medium|low"},
    "date_of_birth": {"value": "MM/DD/YYYY or null", "confidence": "high|medium|low"},
    "phone_number": {"value": "string or null", "confidence": "high|medium|low"},
    "medical_record_number": {"value": "string or null", "confidence": "high|medium|low"},
    "sex": {"value": "M|F|Unknown or null", "confidence": "high|medium|low"},
    "address": {"value": "string or null", "confidence": "high|medium|low"}
  },
  "insurance": {
    "carrier_name": {"value": "string or null", "confidence": "high|medium|low"},
    "member_id": {"value": "string or null", "confidence": "high|medium|low"},
    "group_number": {"value": "string or null", "confidence": "high|medium|low"},
    "plan_type": {"value": "HMO|PPO|EPO|POS|Medicaid|Medicare|Other or null", "confidence": "high|medium|low"},
    "prior_auth_required": {"value": "Yes|No|Unknown", "confidence": "high|medium|low"},
    "prior_auth_number": {"value": "string or null", "confidence": "high|medium|low"}
  },
  "referring_provider": {
    "name": {"value": "string or null", "confidence": "high|medium|low"},
    "npi": {"value": "string or null", "confidence": "high|medium|low"},
    "practice_name": {"value": "string or null", "confidence": "high|medium|low"},
    "phone": {"value": "string or null", "confidence": "high|medium|low"},
    "fax": {"value": "string or null", "confidence": "high|medium|low"}
  },
  "receiving_specialist": {
    "name": {"value": "string or null", "confidence": "high|medium|low"},
    "npi": {"value": "string or null", "confidence": "high|medium|low"},
    "specialty": {"value": "string or null", "confidence": "high|medium|low"},
    "practice_name": {"value": "string or null", "confidence": "high|medium|low"},
    "phone": {"value": "string or null", "confidence": "high|medium|low"},
    "fax": {"value": "string or null", "confidence": "high|medium|low"}
  },
  "clinical": {
    "diagnosis_description": {"value": "string or null", "confidence": "high|medium|low"},
    "icd10_codes": {"value": ["string"], "confidence": "high|medium|low", "source": "explicit|inferred"},
    "reason_for_referral": {"value": "string or null", "confidence": "high|medium|low"},
    "clinical_summary": {"value": "string or null", "confidence": "high|medium|low"},
    "relevant_medications": {"value": ["string"], "confidence": "high|medium|low"},
    "relevant_allergies": {"value": ["string"], "confidence": "high|medium|low"}
  },
  "referral_details": {
    "urgency": {"value": "Routine|Urgent|STAT", "confidence": "high|medium|low"},
    "preferred_date": {"value": "string or null", "confidence": "high|medium|low"},
    "special_instructions": {"value": "string or null", "confidence": "high|medium|low"}
  },
  "dental_specific": {
    "tooth_numbers": {"value": ["string"], "confidence": "high|medium|low"},
    "procedure_requested": {"value": "string or null", "confidence": "high|medium|low"},
    "cdt_codes": {"value": ["string"], "confidence": "high|medium|low", "source": "explicit|inferred"},
    "radiographs_included": {"value": "Yes|No|Unknown", "confidence": "high|medium|low"}
  }
}

User Prompt Template:

Extract referral form data from the following specialist referral call transcript.

Call metadata:

• Date: {call_date}
• Duration: {call_duration}
• Direction: {inbound|outbound}
• Caller ID: {caller_phone_number}

Transcript:

---
{transcript_text}
---

Extract all referral form fields and return the JSON.

Azure OpenAI API Call (Python)

import openai
import json
from azure.identity import DefaultAzureCredential

# Configure for Azure OpenAI (HIPAA-compliant)
client = openai.AzureOpenAI(
    azure_endpoint="https://{your-resource}.openai.azure.com/",
    api_key="{your-azure-openai-key}",
    api_version="2024-08-01-preview"
)

def extract_referral_data(transcript: str, call_metadata: dict) -> dict:
    system_prompt = open('referral_extraction_system_prompt.txt').read()
    user_prompt = f"""Extract referral form data from the following specialist referral call transcript.

Call metadata:
- Date: {call_metadata['date']}
- Duration: {call_metadata['duration']}
- Direction: {call_metadata['direction']}
- Caller ID: {call_metadata['caller_id']}

Transcript:
---
{transcript}
---

Extract all referral form fields and return the JSON."""

    response = client.chat.completions.create(
        model="gpt-5.4",  # deployment name in Azure
        messages=[
            {"role": "system", "content": system_prompt},
            {"role": "user", "content": user_prompt}
        ],
        temperature=0.1,  # Low temperature for consistent extraction
        max_tokens=4000,
        response_format={"type": "json_object"}
    )
    
    extracted = json.loads(response.choices[0].message.content)
    return extracted

Referral Processing Azure Function Pipeline

Type: workflow

An Azure Functions-based serverless pipeline that orchestrates the entire flow from Dialpad call completion webhook to EHR referral form creation. Used as middleware when direct Dialpad-to-HealOS integration is not available, or when building a custom pipeline with Azure OpenAI for EHR systems not supported by HealOS. Deployed in a HIPAA-compliant Azure subscription with BAA.

Implementation:

Azure Functions Pipeline Architecture

Function 1: DialpadWebhookReceiver

Trigger: HTTP (POST) from Dialpad webhook

import azure.functions as func
import json
import logging
from azure.storage.queue import QueueClient
from azure.identity import DefaultAzureCredential

app = func.FunctionApp()

@app.route(route="dialpad-webhook", methods=["POST"])
def dialpad_webhook(req: func.HttpRequest) -> func.HttpResponse:
    """Receives Dialpad call.completed webhook and queues for processing."""
    try:
        payload = req.get_json()
        call_id = payload.get('call_id')
        
        # Validate webhook signature (Dialpad webhook verification)
        # signature = req.headers.get('X-Dialpad-Signature')
        # if not verify_signature(signature, req.get_body()):
        #     return func.HttpResponse(status_code=401)
        
        # Filter: only process calls from referral coordinator extensions
        REFERRAL_EXTENSIONS = ['1001', '1002', '1003']  # Configure per practice
        if payload.get('internal_number') not in REFERRAL_EXTENSIONS:
            return func.HttpResponse("Not a referral line", status_code=200)
        
        # Queue the call for processing
        queue_client = QueueClient.from_connection_string(
            conn_str=os.environ['AzureWebJobsStorage'],
            queue_name='referral-calls'
        )
        queue_client.send_message(json.dumps({
            'call_id': call_id,
            'recording_url': payload.get('recording_url'),
            'transcript': payload.get('transcript'),
            'caller_id': payload.get('external_number'),
            'call_date': payload.get('date_started'),
            'call_duration': payload.get('duration'),
            'direction': payload.get('direction')
        }))
        
        logging.info(f"Queued referral call {call_id} for processing")
        return func.HttpResponse("Accepted", status_code=202)
    except Exception as e:
        logging.error(f"Webhook error: {str(e)}")
        return func.HttpResponse("Error", status_code=500)

Function 2: TranscriptionProcessor

Trigger: Azure Storage Queue message

@app.queue_trigger(arg_name="msg", queue_name="referral-calls",
                   connection="AzureWebJobsStorage")
def process_referral_call(msg: func.QueueMessage):
    """Downloads recording, transcribes if needed, extracts referral data."""
    import requests
    
    call_data = json.loads(msg.get_body().decode())
    
    # Step 1: Get transcript (Dialpad may already provide one)
    transcript = call_data.get('transcript')
    
    if not transcript:
        # Download recording and transcribe via Azure OpenAI Whisper
        recording_response = requests.get(
            call_data['recording_url'],
            headers={'Authorization': f'Bearer {os.environ["DIALPAD_API_KEY"]}'}
        )
        audio_bytes = recording_response.content
        
        # Transcribe with Azure OpenAI Whisper
        from openai import AzureOpenAI
        client = AzureOpenAI(
            azure_endpoint=os.environ['AZURE_OPENAI_ENDPOINT'],
            api_key=os.environ['AZURE_OPENAI_KEY'],
            api_version="2024-08-01-preview"
        )
        
        transcription = client.audio.transcriptions.create(
            model="whisper",
            file=("recording.wav", audio_bytes, "audio/wav"),
            response_format="verbose_json",
            timestamp_granularities=["segment"]
        )
        transcript = transcription.text
    
    # Step 2: Extract referral entities using GPT-5.4
    extracted_data = extract_referral_data(transcript, call_data)
    
    # Step 3: Queue for EHR write-back
    queue_client = QueueClient.from_connection_string(
        conn_str=os.environ['AzureWebJobsStorage'],
        queue_name='ehr-writeback'
    )
    queue_client.send_message(json.dumps({
        'call_id': call_data['call_id'],
        'extracted_data': extracted_data,
        'transcript': transcript,
        'call_metadata': call_data
    }))
    
    logging.info(f"Extracted referral data for call {call_data['call_id']}")

Function 3: EHRWriteBack

Trigger: Azure Storage Queue message

# FHIR patient lookup, ServiceRequest creation, and coordinator notification

@app.queue_trigger(arg_name="msg", queue_name="ehr-writeback",
                   connection="AzureWebJobsStorage")
def ehr_writeback(msg: func.QueueMessage):
    """Creates referral in EHR via FHIR API or HL7."""
    import requests
    
    data = json.loads(msg.get_body().decode())
    extracted = data['extracted_data']
    
    # Get FHIR access token (OAuth2 client credentials)
    token_response = requests.post(
        os.environ['EHR_TOKEN_ENDPOINT'],
        data={
            'grant_type': 'client_credentials',
            'client_id': os.environ['EHR_CLIENT_ID'],
            'client_secret': os.environ['EHR_CLIENT_SECRET'],
            'scope': os.environ['EHR_FHIR_SCOPE']
        }
    )
    access_token = token_response.json()['access_token']
    
    # Look up patient by name and DOB
    patient_name = extracted['patient']['full_name']['value']
    patient_dob = extracted['patient']['date_of_birth']['value']
    
    patient_search = requests.get(
        f"{os.environ['EHR_FHIR_ENDPOINT']}/Patient",
        params={'name': patient_name, 'birthdate': patient_dob},
        headers={'Authorization': f'Bearer {access_token}'}
    )
    
    patient_bundle = patient_search.json()
    if patient_bundle.get('total', 0) == 0:
        logging.warning(f"Patient not found: {patient_name} DOB {patient_dob}")
        # Queue for manual review
        notify_coordinator(data, "Patient not found in EHR")
        return
    
    patient_id = patient_bundle['entry'][0]['resource']['id']
    
    # Create ServiceRequest (referral)
    referral = {
        'resourceType': 'ServiceRequest',
        'status': 'draft',
        'intent': 'order',
        'category': [{'coding': [{
            'system': 'http://snomed.info/sct',
            'code': '3457005',
            'display': 'Patient referral'
        }]}],
        'subject': {'reference': f'Patient/{patient_id}'},
        'reasonCode': [{'text': extracted['clinical']['reason_for_referral']['value']}],
        'note': [{'text': extracted['clinical']['clinical_summary']['value']}],
        'priority': extracted['referral_details']['urgency']['value'].lower()
    }
    
    # Add ICD-10 codes if extracted
    if extracted['clinical']['icd10_codes']['value']:
        referral['reasonCode'][0]['coding'] = [{
            'system': 'http://hl7.org/fhir/sid/icd-10-cm',
            'code': code
        } for code in extracted['clinical']['icd10_codes']['value']]
    
    response = requests.post(
        f"{os.environ['EHR_FHIR_ENDPOINT']}/ServiceRequest",
        json=referral,
        headers={
            'Authorization': f'Bearer {access_token}',
            'Content-Type': 'application/fhir+json'
        }
    )
    
    if response.status_code == 201:
        logging.info(f"Created referral for patient {patient_id}")
        # Notify coordinator that referral is ready for review
        notify_coordinator(data, "Referral created - please review")
    else:
        logging.error(f"EHR write-back failed: {response.status_code} {response.text}")
        notify_coordinator(data, f"EHR write-back failed: {response.text}")

def notify_coordinator(data, message):
    """Send notification to referral coordinator via email or Teams."""
    # Implementation: Send email via SendGrid or Teams message via webhook
    pass

Deployment (Azure CLI):

az group create --name rg-referral-ai --location eastus2

az storage account create --name streferralai --resource-group rg-referral-ai --sku Standard_LRS --kind StorageV2 --min-tls-version TLS1_2

az storage queue create --name referral-calls --account-name streferralai
az storage queue create --name ehr-writeback --account-name streferralai

az functionapp create --name func-referral-ai --resource-group rg-referral-ai --storage-account streferralai --consumption-plan-location eastus2 --runtime python --runtime-version 3.11 --functions-version 4

# use Key Vault references in production)

az functionapp config appsettings set --name func-referral-ai --resource-group rg-referral-ai --settings \
  DIALPAD_API_KEY="@Microsoft.KeyVault(SecretUri=https://kv-referral-ai.vault.azure.net/secrets/dialpad-key/)" \
  AZURE_OPENAI_ENDPOINT="https://oai-referral.openai.azure.com/" \
  AZURE_OPENAI_KEY="@Microsoft.KeyVault(SecretUri=https://kv-referral-ai.vault.azure.net/secrets/openai-key/)" \
  EHR_FHIR_ENDPOINT="https://fhir.ehr-vendor.com/r4" \
  EHR_TOKEN_ENDPOINT="https://auth.ehr-vendor.com/oauth2/token" \
  EHR_CLIENT_ID="@Microsoft.KeyVault(SecretUri=https://kv-referral-ai.vault.azure.net/secrets/ehr-client-id/)" \
  EHR_CLIENT_SECRET="@Microsoft.KeyVault(SecretUri=https://kv-referral-ai.vault.azure.net/secrets/ehr-client-secret/)"

func azure functionapp publish func-referral-ai

requirements.txt:

azure-functions
azure-storage-queue
openai>=1.30.0
requests
azure-identity

Referral Coordinator Review Dashboard

Type: integration

A lightweight web-based review interface that referral coordinators use to verify and approve auto-populated referral forms before they are submitted to the EHR. This acts as the human-in-the-loop quality gate. It displays the original call transcript side-by-side with the extracted referral data, highlights low-confidence fields in yellow, and provides inline editing capabilities. Built as a simple Flask/React app or configured within HealOS's existing review queue.

Implementation:

Review Dashboard Configuration

Option A: Use HealOS Built-in Review Queue (Recommended)

HealOS provides a built-in referral review interface. Configure it as follows:

Option B: Custom Review Dashboard (If HealOS is not used)

Deploy a minimal Flask app on Azure App Service:

# app.py - Referral Review Dashboard
from flask import Flask, render_template, request, jsonify
from azure.storage.table import TableServiceClient
import json
import os

app = Flask(__name__)

@app.route('/referrals')
def referral_list():
    """Display pending referrals for review."""
    table_client = TableServiceClient.from_connection_string(
        os.environ['AZURE_STORAGE_CONNECTION']
    ).get_table_client('referrals')
    
    referrals = table_client.query_entities(
        "status eq 'pending_review'",
        select=['PartitionKey', 'RowKey', 'patient_name', 'specialty',
                'urgency', 'created_at', 'overall_confidence']
    )
    return render_template('referral_list.html', referrals=list(referrals))

@app.route('/referrals/<referral_id>')
def referral_detail(referral_id):
    """Display referral details with transcript and extracted data side-by-side."""
    table_client = TableServiceClient.from_connection_string(
        os.environ['AZURE_STORAGE_CONNECTION']
    ).get_table_client('referrals')
    
    referral = table_client.get_entity('referrals', referral_id)
    extracted_data = json.loads(referral['extracted_json'])
    transcript = referral['transcript']
    
    return render_template('referral_detail.html',
                         referral=referral,
                         extracted=extracted_data,
                         transcript=transcript)

@app.route('/referrals/<referral_id>/approve', methods=['POST'])
def approve_referral(referral_id):
    """Approve referral (with optional edits) and trigger EHR write-back."""
    edited_data = request.get_json()
    
    # Update referral record with edits
    table_client = TableServiceClient.from_connection_string(
        os.environ['AZURE_STORAGE_CONNECTION']
    ).get_table_client('referrals')
    
    table_client.update_entity({
        'PartitionKey': 'referrals',
        'RowKey': referral_id,
        'status': 'approved',
        'edited_json': json.dumps(edited_data),
        'approved_by': request.headers.get('X-User-Email'),
        'approved_at': datetime.utcnow().isoformat()
    })
    
    # Queue for EHR write-back with approved/edited data
    from azure.storage.queue import QueueClient
    queue = QueueClient.from_connection_string(
        os.environ['AZURE_STORAGE_CONNECTION'], 'ehr-writeback'
    )
    queue.send_message(json.dumps({
        'referral_id': referral_id,
        'extracted_data': edited_data,
        'source': 'coordinator_approved'
    }))
    
    return jsonify({'status': 'approved', 'referral_id': referral_id})

if __name__ == '__main__':
    app.run()

HTML Template (referral_detail.html) - Key Elements:

<!-- Two-column layout: transcript left, form right -->
<div class="container">
  <div class="row">
    <div class="col-6" id="transcript-panel">
      <h3>Call Transcript</h3>
      <div class="transcript-text">{{ transcript }}</div>
    </div>
    <div class="col-6" id="form-panel">
      <h3>Extracted Referral Data</h3>
      <form id="referral-form">
        {% for section, fields in extracted.items() %}
          <h4>{{ section | title }}</h4>
          {% for field_name, field_data in fields.items() %}
            <div class="form-group {% if field_data.confidence == 'low' %}bg-warning{% endif %}">
              <label>{{ field_name | replace('_', ' ') | title }}
                <span class="badge badge-{{ field_data.confidence }}">{{ field_data.confidence }}</span>
              </label>
              <input type="text" name="{{ section }}.{{ field_name }}"
                     value="{{ field_data.value or '' }}" class="form-control">
            </div>
          {% endfor %}
        {% endfor %}
        <button type="submit" class="btn btn-success">Approve & Send to EHR</button>
        <button type="button" class="btn btn-danger" onclick="rejectReferral()">Reject</button>
      </form>
    </div>
  </div>
</div>

Consent and Audit Trail Logger

Type: agent A background agent that maintains a comprehensive audit trail of all referral call recordings, consent events, AI processing actions, and EHR write-backs. Required for HIPAA compliance. Logs every access to PHI, every AI processing event, and every consent decision. Integrates with the Compliancy Group platform for compliance reporting.

Implementation:

Audit Trail Agent Implementation

Azure Table Storage Schema:

Table: AuditLog

• PartitionKey: YYYY-MM (month partition for efficient querying)
• RowKey: UUID (unique event ID)
• Timestamp: auto-populated by Azure
• EventType: CALL_RECORDED | CONSENT_OBTAINED | CONSENT_DECLINED | TRANSCRIPT_CREATED | ENTITY_EXTRACTED | REFERRAL_CREATED | REFERRAL_APPROVED | REFERRAL_SUBMITTED | PHI_ACCESSED | DATA_DELETED
• CallId: Dialpad call ID
• PatientIdentifier: hashed MRN or name (not raw PHI in audit log)
• UserId: email of staff member who performed action
• SystemComponent: DIALPAD | HEALOS | AZURE_OPENAI | EHR | REVIEW_DASHBOARD
• Action: human-readable description
• IPAddress: source IP
• Success: true/false
• ErrorDetail: error message if Success=false
• DataClassification: PHI | NON_PHI

Python Audit Logger Module

# audit_logger.py
import uuid
import hashlib
from datetime import datetime
from azure.data.tables import TableServiceClient
import os

class AuditLogger:
    def __init__(self):
        self.table_client = TableServiceClient.from_connection_string(
            os.environ['AZURE_STORAGE_CONNECTION']
        ).get_table_client('AuditLog')
    
    def log_event(self, event_type: str, call_id: str = None,
                  patient_identifier: str = None, user_id: str = None,
                  system_component: str = None, action: str = None,
                  ip_address: str = None, success: bool = True,
                  error_detail: str = None):
        
        # Hash patient identifier for audit log (don't store raw PHI)
        hashed_patient = None
        if patient_identifier:
            hashed_patient = hashlib.sha256(
                patient_identifier.encode()
            ).hexdigest()[:16]
        
        entity = {
            'PartitionKey': datetime.utcnow().strftime('%Y-%m'),
            'RowKey': str(uuid.uuid4()),
            'EventType': event_type,
            'CallId': call_id or '',
            'PatientIdentifier': hashed_patient or '',
            'UserId': user_id or 'SYSTEM',
            'SystemComponent': system_component or '',
            'Action': action or '',
            'IPAddress': ip_address or '',
            'Success': success,
            'ErrorDetail': error_detail or '',
            'DataClassification': 'PHI' if patient_identifier else 'NON_PHI',
            'EventTimestamp': datetime.utcnow().isoformat()
        }
        
        self.table_client.create_entity(entity)
    
    def log_consent(self, call_id: str, patient_name: str,
                    consent_given: bool, consent_method: str):
        self.log_event(
            event_type='CONSENT_OBTAINED' if consent_given else 'CONSENT_DECLINED',
            call_id=call_id,
            patient_identifier=patient_name,
            system_component='DIALPAD',
            action=f'Call recording consent {"granted" if consent_given else "declined"} via {consent_method}'
        )
    
    def log_transcription(self, call_id: str, patient_name: str, success: bool):
        self.log_event(
            event_type='TRANSCRIPT_CREATED',
            call_id=call_id,
            patient_identifier=patient_name,
            system_component='AZURE_OPENAI',
            action='Call audio transcribed via Whisper API',
            success=success
        )
    
    def log_extraction(self, call_id: str, patient_name: str,
                       fields_extracted: int, confidence: str):
        self.log_event(
            event_type='ENTITY_EXTRACTED',
            call_id=call_id,
            patient_identifier=patient_name,
            system_component='AZURE_OPENAI',
            action=f'Extracted {fields_extracted} fields with {confidence} confidence'
        )
    
    def log_ehr_writeback(self, call_id: str, patient_name: str,
                          ehr_resource_id: str, success: bool, error: str = None):
        self.log_event(
            event_type='REFERRAL_SUBMITTED',
            call_id=call_id,
            patient_identifier=patient_name,
            system_component='EHR',
            action=f'Referral written to EHR as {ehr_resource_id}',
            success=success,
            error_detail=error
        )

# Usage in pipeline functions:
audit = AuditLogger()
audit.log_consent('call_123', 'John Smith', consent_given=True, consent_method='automated_announcement')
audit.log_transcription('call_123', 'John Smith', success=True)
audit.log_extraction('call_123', 'John Smith', fields_extracted=18, confidence='high')
audit.log_ehr_writeback('call_123', 'John Smith', 'ServiceRequest/456', success=True)

Compliance Reporting Query

def generate_monthly_report(year_month: str):
    entities = table_client.query_entities(
        f"PartitionKey eq '{year_month}'"
    )
    
    report = {
        'total_calls_recorded': 0,
        'consents_obtained': 0,
        'consents_declined': 0,
        'referrals_processed': 0,
        'ehr_writebacks_successful': 0,
        'ehr_writebacks_failed': 0,
        'phi_access_events': 0
    }
    
    for entity in entities:
        if entity['EventType'] == 'CALL_RECORDED': report['total_calls_recorded'] += 1
        elif entity['EventType'] == 'CONSENT_OBTAINED': report['consents_obtained'] += 1
        elif entity['EventType'] == 'CONSENT_DECLINED': report['consents_declined'] += 1
        elif entity['EventType'] == 'ENTITY_EXTRACTED': report['referrals_processed'] += 1
        elif entity['EventType'] == 'REFERRAL_SUBMITTED':
            if entity['Success']: report['ehr_writebacks_successful'] += 1
            else: report['ehr_writebacks_failed'] += 1
        elif entity['EventType'] == 'PHI_ACCESSED': report['phi_access_events'] += 1
    
    return report

Testing & Validation

• AUDIO CAPTURE TEST: Place a 5-minute test referral call between two staff members using the Jabra Speak2 75 on the referral coordinator's workstation. Verify in Dialpad Admin > Call History that (a) the call was recorded, (b) the consent announcement played at call start, (c) the recording audio is clear with both speakers intelligible, and (d) the Dialpad AI transcript is generated within 2 minutes of call completion.
• CONSENT WORKFLOW TEST: Place a test call and have the 'caller' verbally decline recording. Verify the referral coordinator can disable recording mid-call using the configured method (*9 or Dialpad UI toggle). Confirm the call recording stops, no transcript is generated for the non-consented portion, and the coordinator is redirected to the manual referral entry workflow.
• TRANSCRIPTION ACCURACY TEST: Process 10 sample referral calls (use scripted role-play scenarios covering different specialties, insurance types, and urgency levels). Compare Dialpad or Azure Whisper transcripts against manual transcription. Measure word error rate (WER). Target: WER below 10% for clear audio, below 15% for calls with background noise.
• ENTITY EXTRACTION ACCURACY TEST: Using the 10 sample call transcripts, run through the HealOS Referrals Agent (or custom Azure OpenAI extraction pipeline). For each call, compare every extracted field against the 'ground truth' values from the script. Calculate per-field accuracy. Target: >90% overall accuracy, >95% for patient name, DOB, and insurance ID. Document any fields consistently below 85% and adjust extraction templates.
• FHIR/EHR WRITE-BACK TEST: Using the extracted data from one test referral, execute the FHIR ServiceRequest creation API call against the practice's EHR sandbox/test environment. Verify the referral appears in the EHR referral module with all fields correctly populated. Check that the referral status is 'draft' (not auto-submitted). Verify the referring provider, receiving specialist, diagnosis, and clinical summary all display correctly in the EHR's referral form view.
• PATIENT LOOKUP TEST: Test the patient matching logic with 5 scenarios: (a) exact name and DOB match, (b) name with slight spelling variation, (c) patient not found in EHR, (d) multiple patients with same name, (e) DOB format variation. Verify the system correctly matches in case (a), flags for manual review in cases (b-e), and never creates a duplicate patient record.
• END-TO-END WORKFLOW TEST: Execute a complete referral call from start to finish with a test patient in the EHR sandbox. Verify: consent announcement plays → call is recorded → transcript is generated → entities are extracted → referral coordinator reviews in dashboard → coordinator approves → referral form is created in EHR with correct data → audit log captures all events. Measure total time from call completion to referral form ready for review. Target: under 5 minutes.
• MULTI-SPECIALTY TEMPLATE TEST: Process one test referral call for each of the top 5 specialty types configured during setup (e.g., cardiology, orthopedics, gastroenterology, oral surgery, endodontics). Verify that specialty-specific fields are correctly extracted (e.g., tooth numbers for dental, cardiac symptoms for cardiology). Confirm the correct EHR referral template is selected for each specialty.
• HIPAA SECURITY TEST: Verify (a) all data in transit uses TLS 1.2+ (check with browser dev tools and ssllabs.com scan), (b) all stored data is encrypted at rest (verify Azure Storage encryption settings, Dialpad encryption status, HealOS security page), (c) MFA is enforced for all user accounts on all platforms, (d) role-based access correctly restricts provider-level data from non-clinical staff, (e) audit logs are being populated with all PHI access events.
• FAILOVER AND ERROR HANDLING TEST: Simulate common failure scenarios: (a) Dialpad webhook fails to deliver (verify retry logic and dead-letter queue), (b) Azure OpenAI API returns an error (verify graceful degradation and coordinator notification), (c) EHR FHIR endpoint is temporarily unavailable (verify retry with exponential backoff and referral stays in review queue), (d) extraction confidence is low on critical fields (verify form is flagged for manual entry rather than submitted with bad data).
• LOAD AND PERFORMANCE TEST: Process 20 referral calls in rapid succession (simulating a busy Monday morning) and verify: (a) no calls are dropped or lost in the pipeline, (b) processing time remains under 5 minutes per referral, (c) the review dashboard remains responsive, (d) EHR write-backs do not time out or create duplicate referrals.
• DENTAL PMS INTEGRATION TEST (dental practices only): For OraCore deployments, verify the Dentrix API Exchange or Open Dental API correctly receives referral data. Create a test outgoing referral in the PMS and confirm patient demographics, tooth numbers, procedure codes, and specialist information are correctly populated. Verify the referral letter is generated and available for eFax transmission.

Client Handoff

Client Handoff Checklist

Training Topics (Conduct 2 sessions: 1 for clinical staff, 1 for front desk/admin)

Documentation to Leave Behind

Success Criteria to Review Together

Go-Live Sign-Off

Obtain written sign-off from practice owner/manager confirming: system is operational, staff are trained, compliance documentation is complete, and the practice accepts responsibility for ongoing consent management and referral review approval. Provide 30-day hypercare support window with daily check-ins for the first week, then twice-weekly for the remaining 3 weeks.

Maintenance

Ongoing Maintenance Responsibilities

Weekly Tasks (15–30 minutes)

• Review HealOS/Azure dashboard for processing errors or failed extractions
• Check Dialpad call recording storage utilization and retention compliance
• Verify all referral coordinator accounts are active and MFA-enabled
• Review audit log for any anomalous PHI access patterns

Monthly Tasks (1–2 hours)

• Generate and review extraction accuracy report (target: maintain >90% accuracy; if it drops below 85%, trigger template retuning)
• Review referral volume trends and system utilization
• Verify all software platforms are on current versions (Dialpad desktop app, browser versions, HealOS updates)
• Check Azure OpenAI API usage and costs against budget (if using custom pipeline)
• Generate HIPAA compliance report from audit logs and share with practice compliance officer
• Test backup/restore procedures for configuration data

Quarterly Tasks (2–4 hours)

• Conduct HIPAA security risk assessment mini-review (full assessment annually)
• Review and update referral form templates for any new specialties or changed form requirements
• Review BAA status for all vendors (ensure none have expired or been modified)
• Update consent announcement script if regulations have changed
• Performance review meeting with practice manager: review ROI metrics, gather feedback, plan optimizations
• Test disaster recovery: simulate platform outage and verify manual fallback workflow is still documented and staff remember it

Annual Tasks

• Full HIPAA security risk assessment
• Renew or review all vendor contracts and BAAs
• Re-negotiate pricing based on usage data (opportunity to optimize tier/plan)
• Review state call recording consent law changes
• Comprehensive system audit: data retention compliance, access control review, encryption verification
• Staff refresher training (30-minute session)

Model/AI Retraining Triggers

• Extraction accuracy drops below 85% for 2 consecutive weeks
• Practice adds a new referral specialty (requires new extraction template)
• EHR vendor updates referral form schema or API version
• Significant change in call volume or referral workflow
• New staff members with different speech patterns or accents consistently produce lower accuracy

SLA Considerations

• Uptime target: 99.5% (aligned with Dialpad and HealOS SLAs)
• Response time for Tier 1 issues: 4 business hours
• Response time for Tier 2 issues (extraction failures, integration errors): 8 business hours
• Response time for Tier 3 issues (data breach, complete system failure): 1 hour
• Monthly service review call with practice stakeholder

Escalation Paths

Alternatives

Enterprise Ambient AI Scribe (DAX Copilot / Abridge / Suki)

Instead of the HealOS + Dialpad stack, deploy Microsoft Dragon Copilot (DAX) at $600/provider/month, Abridge at $400–600/provider/month, or Suki at $399/provider/month. These enterprise-grade platforms offer deeper EHR integration (especially DAX with Epic), broader clinical documentation capabilities beyond just referrals, and dedicated implementation support teams. The referral capture would be handled through their general ambient recording capabilities plus custom workflow configuration for referral-specific data extraction.

Tradeoffs

• Cost: 4–12x higher per-provider monthly cost ($399–$600 vs. $49–$75).
• Complexity: DAX requires significant IT infrastructure and 3–6 month deployment timelines.
• Capability: These platforms offer comprehensive clinical documentation beyond referrals, which may justify the cost for practices that also want progress notes, H&Ps, and discharge summaries automated.
• When to recommend: practices with 10+ providers already on Epic or athenahealth who want a single ambient AI platform for all documentation needs, not just referrals.
• Not recommended for practices that only need referral workflow automation.

Freed AI for Budget-Conscious Small Practices

Deploy Freed AI at $39–$99/provider/month as the ambient AI scribe instead of HealOS. Freed positions itself as the simplest, fastest-to-deploy option for practices without IT departments. Use Freed for call transcription, then export the transcript and use a manual or semi-automated process to populate referral forms. Freed does not have a dedicated referral agent, so the referral form auto-population would require either manual copy-paste from Freed's notes or a custom middleware component using Azure OpenAI.

Tradeoffs

• Cost: Similar to HealOS ($39–$99 vs. $49).
• Simplicity: Freed is easier to deploy for pure transcription (no EHR integration required).
• Limitation: No dedicated referral agent — the core value proposition of auto-populating referral forms is lost unless you build custom middleware.
• When to recommend: solo practitioners or 2-provider practices that primarily want transcription of referral calls for documentation purposes, with manual form population acceptable.
• Not recommended if the primary goal is eliminating manual referral form data entry.

Custom Azure OpenAI Pipeline (Build-Your-Own)

Skip HealOS and Dialpad's built-in AI entirely. Build a custom pipeline using Azure OpenAI Whisper for transcription ($0.006/min) and GPT-5.4 for entity extraction, with custom Azure Functions middleware connecting the practice's existing phone system to the EHR via FHIR APIs. This approach gives the MSP maximum control over the pipeline, customization capability, and potentially higher margins since the per-call AI cost is pennies rather than dollars.

Tradeoffs

• Cost: Lowest per-call AI cost ($0.01–$0.05 per referral call vs. $49+/provider/month).
• Margin: Highest MSP margin potential — charge $150–$200/provider/month for a service that costs $30–$80/month in Azure consumption.
• Complexity: Highest — requires Python development, Azure DevOps, FHIR API expertise, and ongoing prompt engineering.
• Timeline: 8–16 weeks vs. 4–6 weeks for turnkey.
• Risk: MSP owns the entire pipeline including uptime, accuracy, and compliance. No vendor support to fall back on.
• When to recommend: MSPs with in-house developers seeking maximum control and margin, or practices with EHR systems not supported by HealOS or other turnkey platforms.

Dental-Specific: Bola AI + Dentrix Integration

For dental practices using Dentrix, deploy Bola AI instead of OraCore. Bola AI is purpose-built for dental workflows with deep Dentrix and Open Dental integration. While pricing requires direct vendor contact, it offers dental-specific NLP that understands CDT codes, tooth numbering systems, and dental specialty referral workflows natively.

• Cost: Unknown (contact vendor for pricing) — likely $100–$300/month.
• Capability: More dental-specific than OraCore for practices with complex referral needs (implant cases, TMJ, sleep dentistry).
• Limitation: Newer vendor with less market validation; fewer reviews and case studies available.
• When to recommend: dental practices with high-volume specialist referrals (especially oral surgery and periodontics) where dental-specific NLP accuracy is critical.
• Not recommended if the practice also has medical providers (use HealOS for mixed medical/dental).

Phone System Replacement: RingCentral RingEX Instead of Dialpad

Use RingCentral RingEX ($20–$35/user/month) instead of Dialpad for the HIPAA-compliant phone system layer. RingCentral offers similar AI transcription capabilities, HIPAA compliance with BAA, and call recording features. RingCentral has a larger market share in healthcare and may be a better fit for practices that already use RingCentral or want a more established vendor.

Tradeoffs:

• Cost: Slightly higher at $20–$35/user/month vs. $15–$25/user/month for Dialpad.
• Integration: RingCentral has a broader app marketplace but Dialpad's native AI transcription may be more tightly integrated.
• Market position: RingCentral is the larger, more established vendor — lower risk for practices concerned about vendor stability.
• When to recommend: practices that already use RingCentral, prefer a larger vendor, or need advanced call center features (IVR, call queuing, skills-based routing) for their referral lines.