Voice Conversations

AI-powered voice conversations for patient outreach, benefits verification, and insurance inquiries. The system supports both patient-facing inbound calls and outbound insurance provider interactions.

Provider Abstraction

The Voice API is provider-agnostic. It exposes a unified interface for managing voice calls regardless of the underlying telephony infrastructure. This allows swapping providers without changing client integrations.

The Voice Call object

A Voice Call represents a conversation between the AI agent and either a patient or an insurance representative. Calls are analyzed for insights after completion.

Attributes

idinteger

Unique identifier for the voice call.

call_idstring

External conversation ID from voice provider.

phone_numberstring

Caller/callee phone number.

directionstring

Call direction.

inboundoutbound

statusstring

Current call status.

in_progresscompletedfailed

duration_secondsinteger

Total call duration in seconds.

patient_idinteger

Linked patient ID (null until verified).

agent_typestring

Type of AI agent.

patientinsurance

call_typestring

Type of call.

patientinsurance_outbound

topics_discussedarray

Topics identified during the call.

medications_discussedarray

Medications mentioned during the call.

call_outcomestring

Outcome of the call.

coverage_confirmedpa_requiredcallback_requestedadverse_event

patient_satisfaction_scoreinteger

AI-inferred satisfaction (1-5).

analysis_metadataobject

AI-generated call analysis and insights.

The Voice Call object

{
  "id": 123,
  "call_id": "conv_abc123",
  "phone_number": "+14155551234",
  "direction": "inbound",
  "status": "completed",
  "duration_seconds": 245,
  "patient_id": 456,
  "agent_type": "patient",
  "call_type": "patient",
  "verified": true,
  "topics_discussed": [
    "benefits_verification",
    "pa_requirements"
  ],
  "medications_discussed": ["Keytruda"],
  "jcodes_discussed": {
    "Keytruda": "J9271"
  },
  "call_outcome": "coverage_confirmed",
  "patient_satisfaction_score": 4,
  "callback_requested": false,
  "follow_up_actions": [
    {
      "action": "Submit PA request",
      "priority": "high",
      "status": "pending",
      "assigned_to": "provider"
    }
  ],
  "analysis_metadata": {
    "summary": {
      "overview": "Patient verified coverage",
      "patient_concern": "PA requirements",
      "resolution": "Confirmed coverage"
    },
    "key_findings": [
      "Prior authorization required",
      "$50 remaining on deductible"
    ]
  },
  "created_at": "2024-12-18T10:30:00Z",
  "completed_at": "2024-12-18T10:34:05Z"
}

Retrieve a voice call

Retrieve details of a specific voice call by ID.

GET/voice/calls/{voice_call_id}

Path Parameters

voice_call_idintegerrequired

The voice call ID.

Request

curl https://api.isomera.ai/v1/voice/calls/123 \
  -H "Authorization: Bearer sk_live_..."

Response

{
  "id": 123,
  "call_id": "conv_abc123",
  "phone_number": "+14155551234",
  "direction": "inbound",
  "status": "completed",
  "duration_seconds": 245,
  "patient_id": 456,
  "call_outcome": "coverage_confirmed",
  "patient_satisfaction_score": 4,
  "created_at": "2024-12-18T10:30:00Z"
}

List patient calls

Retrieve all voice calls for a specific patient.

GET/voice/patients/{patient_id}/calls

Path Parameters

patient_idintegerrequired

The patient ID.

Query Parameters

limitintegeroptional

Maximum records to return.

Default: 10

offsetintegeroptional

Number of records to skip.

Default: 0

Request

curl https://api.isomera.ai/v1/voice/patients/456/calls \
  -H "Authorization: Bearer sk_live_..."

Response

{
  "patient_id": 456,
  "calls": [
    {
      "id": 123,
      "call_id": "conv_abc123",
      "status": "completed",
      "duration_seconds": 245,
      "call_outcome": "coverage_confirmed",
      "created_at": "2024-12-18T10:30:00Z"
    }
  ],
  "count": 1
}

Voice function calls

During voice conversations, the AI agent can invoke various functions to look up information, verify benefits, and take actions. These are handled via webhooks from the voice provider.

Available Functions

Function	Description
`patient_lookup`	Verify patient identity using 3-factor auth
`verify_benefits`	Check coverage, deductibles, copays
`check_pa_requirements`	Query prior authorization requirements
`flag_adverse_event`	Report adverse events for review
`request_callback`	Schedule human callback
`send_follow_up_email`	Send coverage summary email

patient_lookup request

{
  "first_name": "John",
  "last_name": "Doe",
  "dob": "1985-03-15",
  "member_id": "ABC123456",
  "payer_name": "Aetna"
}

patient_lookup response

{
  "patient_id": 456,
  "patient_name": "John Doe",
  "verified": true,
  "confidence": 1.0,
  "message": "I've verified your identity."
}

verify_benefits

Retrieves coverage information including deductibles, copays, and out-of-pocket maximums. Also queries prior authorization requirements from payer policy documents.

Parameters

patient_idintegerrequired

The verified patient ID.

medicationstringoptional

Medication name to check coverage for.

Request

{
  "patient_id": 456,
  "medication": "Keytruda"
}

Response

{
  "job_id": "bv-456-1702900200",
  "status": "completed",
  "payer": "Aetna",
  "medication": "Keytruda",
  "deductible": 500,
  "deductible_remaining": 150,
  "out_of_pocket_max": 5000,
  "out_of_pocket_remaining": 3500,
  "copay_pharmacy": 50,
  "copay_specialty": 100,
  "coinsurance_percentage": 20,
  "pa_required": true,
  "message": "Coverage verified for Keytruda."
}

flag_adverse_event

Critical patient safety function. Automatically detects and flags adverse events with appropriate severity levels and recommended actions.

Parameters

patient_idintegerrequired

The patient ID.

event_descriptionstringrequired

Description of the adverse event.

severitystringrequired

Severity level.

mildmoderateseverelife-threatening

medication_namestringoptional

Related medication.

symptomsarrayoptional

List of symptoms reported.

Severity Levels

mild: Monitor, contact doctor if worsens
moderate: Contact doctor soon
severe: Contact doctor immediately
life-threatening: Call 911 / go to ER

Request

{
  "patient_id": 456,
  "event_description": "Severe headache and nausea",
  "severity": "moderate",
  "medication_name": "Keytruda",
  "symptoms": ["headache", "nausea"]
}

Response

{
  "case_number": "AE-456-1702900500",
  "flagged": true,
  "requires_immediate_action": false,
  "severity": "moderate",
  "message": "Flagged for medical team review."
}

J-Code lookup

Look up HCPCS J-codes for medications discussed during calls.

POST/voice/jcodes/lookup

Body Parameters

medicationsarrayrequired

List of medication names to look up.

Request

curl https://api.isomera.ai/v1/voice/jcodes/lookup \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "medications": ["Keytruda", "Opdivo", "Herceptin"]
  }'

Response

{
  "jcodes": {
    "Keytruda": "J9271",
    "Opdivo": "J9299",
    "Herceptin": "J9355"
  }
}

Voice webhooks

The voice system uses webhooks to receive events from the telephony provider and to handle function calls during conversations.

Function Call Webhook

POST/voice/webhook

Receives function call requests during active conversations. The response is returned to the voice agent to continue the conversation.

Post-Call Webhook

POST/webhooks/voice/post-call

Receives post-call data including audio recording URL and triggers AI analysis of the completed conversation.

Function call webhook payload

{
  "conversation_id": "conv_abc123",
  "function_name": "patient_lookup",
  "parameters": {
    "first_name": "John",
    "last_name": "Doe",
    "dob": "1985-03-15",
    "member_id": "ABC123456"
  }
}

Post-call webhook payload

{
  "conversation_id": "conv_abc123",
  "status": "completed",
  "duration_seconds": 245,
  "audio_url": "https://storage.../recording.mp3",
  "transcript": "Agent: Hello, this is..."
}

Real-time transcription

During live calls, transcript utterances can be streamed to the backend for real-time processing and insight extraction.

POST/voice/{voice_call_id}/add-utterance

Body Parameters

textstringrequired

The utterance text.

speakerstringrequired

Who spoke.

useragent

timestampstringoptional

ISO 8601 timestamp.

The system automatically extracts insights from utterances including:

Topics: benefits_verification, pa_requirements, adverse_event
Medications: Drug names with J-code lookups
Sentiments: Emotional state detection

Request

curl https://api.isomera.ai/v1/voice/123/add-utterance \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "text": "I need to check my benefits for Keytruda",
    "speaker": "user",
    "timestamp": "2024-12-18T10:30:15Z"
  }'

Response

{
  "success": true,
  "utterance_id": 789,
  "voice_call_id": 123,
  "duplicate": false,
  "insights_extracted": true
}