Patients
The Patient object represents an individual enrolled in care programs. Patients can be created, updated, and retrieved via the API, and are automatically linked to voice conversations and benefits verification.
The Patient object
A Patient represents an individual in your healthcare system. Each patient has demographic information, insurance details, and enrollment status.
Unique identifier for the patient.
Patient's first name.
Patient's last name.
Date of birth in YYYY-MM-DD format.
Primary phone number in E.164 format.
Email address.
Medical record number (auto-generated if not provided).
Insurance payer identifier (e.g., aetna, cigna, uhc).
Insurance member ID number.
List of medications associated with the patient.
Current status.
Whether patient has reported any adverse events.
Average satisfaction score from conversations (1-5).
ISO 8601 timestamp of when the patient was created.
{
"id": 123,
"first_name": "John",
"last_name": "Doe",
"date_of_birth": "1985-03-15",
"phone": "+14155551234",
"email": "john.doe@example.com",
"mrn": "MRN1123",
"member_id": "ABC123456",
"payer_id": "aetna",
"group_number": "GRP001",
"address_line1": "123 Main St",
"city": "San Francisco",
"state": "CA",
"zip_code": "94102",
"status": "active",
"has_adverse_events": false,
"avg_satisfaction_score": 4.5,
"total_conversations": 3,
"medications": ["Keytruda", "Metformin"],
"created_at": "2024-01-15T10:30:00Z"
}List all patients
Returns a paginated list of patients. Supports filtering and search.
/patientsMaximum records to return.
Default: 20
Number of records to skip.
Default: 0
Search by name, phone, email, MRN, or member ID.
Filter by status.
Filter by insurance payer.
Filter patients with/without adverse events.
Minimum satisfaction score (1-5).
Maximum satisfaction score (1-5).
curl https://api.isomera.ai/v1/patients \
-H "Authorization: Bearer sk_live_..."{
"items": [
{
"id": 123,
"first_name": "John",
"last_name": "Doe",
"date_of_birth": "1985-03-15",
"phone": "+14155551234",
"email": "john.doe@example.com",
"mrn": "MRN1123",
"member_id": "ABC123456",
"payer_id": "aetna",
"status": "active",
"has_adverse_events": false,
"avg_satisfaction_score": 4.5,
"total_conversations": 3,
"medications": ["Keytruda", "Metformin"],
"created_at": "2024-01-15T10:30:00Z"
}
],
"total": 150,
"page": 1,
"page_size": 20
}Create a patient
Creates a new patient record in the system.
/patientsPatient first name.
Patient last name.
Date of birth (YYYY-MM-DD).
Phone number in E.164 format.
Email address.
Insurance payer identifier.
Insurance member ID.
Insurance group number.
curl https://api.isomera.ai/v1/patients \
-H "Authorization: Bearer sk_live_..." \
-H "Content-Type: application/json" \
-d '{
"first_name": "John",
"last_name": "Doe",
"date_of_birth": "1985-03-15",
"phone": "+14155551234",
"email": "john.doe@example.com",
"member_id": "ABC123456",
"payer_id": "aetna",
"group_number": "GRP001"
}'{
"id": 124,
"first_name": "John",
"last_name": "Doe",
"mrn": "MRN1124",
"status": "active",
"created_at": "2024-12-18T15:30:00Z"
}Retrieve a patient
Retrieves an existing patient by their ID.
/patients/{patient_id}The patient ID.
curl https://api.isomera.ai/v1/patients/123 \
-H "Authorization: Bearer sk_live_..."{
"id": 123,
"first_name": "John",
"last_name": "Doe",
"date_of_birth": "1985-03-15",
"phone": "+14155551234",
"email": "john.doe@example.com",
"payer_id": "aetna",
"member_id": "ABC123456",
"medications": ["Keytruda"],
"status": "active",
"created_at": "2024-01-15T10:30:00Z"
}Update a patient
Updates an existing patient. Only provided fields are updated.
/patients/{patient_id}The patient ID.
Updated phone number.
Updated email address.
Updated payer identifier.
Updated member ID.
Updated status.
curl -X PUT https://api.isomera.ai/v1/patients/123 \
-H "Authorization: Bearer sk_live_..." \
-H "Content-Type: application/json" \
-d '{
"phone": "+14155559999",
"payer_id": "bcbs"
}'{
"id": 123,
"first_name": "John",
"last_name": "Doe",
"phone": "+14155559999",
"payer_id": "bcbs",
"status": "active",
"updated_at": "2024-12-18T11:00:00Z"
}Delete a patient
Soft deletes a patient by setting status to inactive.
/patients/{patient_id}The patient ID.
Patients are not permanently deleted. The status is set to "inactive" and the record is preserved for compliance purposes.
curl -X DELETE https://api.isomera.ai/v1/patients/123 \
-H "Authorization: Bearer sk_live_..."{
"success": true,
"message": "Patient deactivated"
}Get verification status
Retrieve the most recent benefits verification status for a patient, including verification method results and extracted benefits data.
/patients/{patient_id}/verification-statusThe patient ID.
curl https://api.isomera.ai/v1/patients/123/verification-status \
-H "Authorization: Bearer sk_live_..."{
"verification_id": 456,
"pa_case_id": 789,
"status": "VERIFIED",
"methods": {
"api": {
"status": "completed",
"success": true,
"duration": 2.5
},
"voice": {
"status": "completed",
"success": true,
"duration": 180.0
}
},
"benefits": {
"deductible_individual": 500.00,
"deductible_family": 1500.00,
"copay_pcp": 25.00,
"copay_specialist": 50.00,
"out_of_pocket_max": 5000.00,
"coverage_status": "active",
"deductible_met_ytd": 350.00,
"tier_1_copay": 10.00,
"tier_2_copay": 30.00,
"tier_3_copay": 60.00
},
"field_sources": {
"deductible_individual": "api",
"copay_specialist": "voice"
}
}Patient medications
Manage medications associated with a patient, including prescription status, prior authorization requirements, and step therapy tracking.
List medications
/patients/{patient_id}/medicationsAdd medication
/patients/{patient_id}/medicationsName of the medication.
National Drug Code.
Whether medication is currently prescribed.
Date prescribed (YYYY-MM-DD).
Name of prescribing physician.
NPI of prescribing physician.
Whether prior authorization is required.
Prior authorization status.
Sync from conversations
Extract medications discussed in voice conversations and automatically create medication records.
/patients/{patient_id}/medications/synccurl https://api.isomera.ai/v1/patients/123/medications \
-H "Authorization: Bearer sk_live_..." \
-H "Content-Type: application/json" \
-d '{
"medication_name": "Keytruda",
"ndc_code": "00006-3026-01",
"is_prescribed": true,
"prescribed_date": "2024-12-01",
"prescriber_name": "Dr. Smith",
"prescriber_npi": "1234567890",
"pa_required": true,
"pa_status": "pending"
}'{
"id": 1,
"patient_id": 123,
"medication_name": "Keytruda",
"ndc_code": "00006-3026-01",
"is_prescribed": true,
"prescribed_date": "2024-12-01T00:00:00Z",
"prescriber_name": "Dr. Smith",
"prescriber_npi": "1234567890",
"pa_required": true,
"pa_status": "pending",
"step_therapy_required": false,
"step_therapy_completed": false,
"step_therapy_drugs": [],
"first_mentioned_at": "2024-11-15T10:00:00Z",
"conversation_ids": [45, 67],
"created_at": "2024-12-18T15:30:00Z"
}