--- title: "List Patients" method: GET path: "/v1/patients" tags: ["Patients"] --- # List Patients `GET /v1/patients` ## Query parameters - `workflow_stage_ids[]` string[], nullable — Filter by multiple workflow stage IDs (OR) - `include_unassigned` boolean — Include patients with no workflow stage (combines with workflow_stage_ids via OR) - `tags[]` string[], nullable — Filter by tag IDs - `insurance_ids[]` string[], nullable — Filter by insurance IDs - `states[]` States[], nullable — Filter by states - `location_ids[]` string[], nullable — Filter by company location IDs - `organization_ids[]` string[], nullable — Filter by company organization IDs - `created_from[]` PatientCreatedFrom[], nullable — Filter by created_from sources - `eligibility_status[]` EligibilityStatus[], nullable — Filter by eligibility check status - `eligibility_filter_mode` 'any' | 'primary' | 'secondary' | 'tertiary' | 'quaternary' — Eligibility filter mode — which payor tier to check, or any - `sync_status[]` SyncStatus[], nullable — Filter by sync status - `plan_name` string, nullable — Filter by plan name (partial match) - `plan_types[]` InsurancePlanType[], nullable — Filter by plan types - `group_description` string, nullable — Filter by group description (partial match) - `group_number` string, nullable — Filter by group number (partial match) - `expand[]` PatientExpand[], nullable — Fields to expand in the response - `page` integer, nullable - `limit` integer, nullable - `q` string, nullable - `id` string, uuid, nullable - `workflow_stage_id` string, nullable - `assigned_to` string, nullable - `status` 'active' | 'inactive' | 'all' — Filter options for patient status (active/inactive/all) - `phone_number` string, nullable - `email` string, nullable - `external_id` string, nullable - `first_name` string, nullable - `last_name` string, nullable - `date_of_birth` string, nullable - `tag_filter_mode` 'any' | 'all' | 'exclude_any' | 'exclude_all' — Tag filter mode for patient queries - `created_gte` string, date-time, nullable - `created_lte` string, date-time, nullable - `updated_gte` string, date-time, nullable - `updated_lte` string, date-time, nullable ## Response `200` Successful Response - PatientList — List response for patients - `data` Patient[], required - `id` string, uuid, required - `created_at` string, nullable, required - `updated_at` string, nullable, required - `first_name` string, nullable - `last_name` string, nullable - `middle_name` string, nullable - `phone_number` string, nullable - `additional_phone_number` string, nullable - `email` string, nullable - `date_of_birth` string, nullable - `gender` 'male' | 'female' | 'other' — Gender enum matching Prisma - `address` string, nullable - `address2` string, nullable - `city` string, nullable - `state` 'alabama' | 'alaska' | 'arizona' | 'arkansas' | 'california' | 'colorado' | 'connecticut' | 'delaware' | 'florida' | 'georgia' | 'hawaii' | 'idaho' | 'illinois' | 'indiana' | 'iowa' | 'kansas' | 'kentucky' | 'louisiana' | 'maine' | 'maryland' | 'massachusetts' | 'michigan' | 'minnesota' | 'mississippi' | 'missouri' | 'montana' | 'nebraska' | 'nevada' | 'new_hampshire' | 'new_jersey' | 'new_mexico' | 'new_york' | 'north_carolina' | 'north_dakota' | 'ohio' | 'oklahoma' | 'oregon' | 'pennsylvania' | 'rhode_island' | 'south_carolina' | 'south_dakota' | 'tennessee' | 'texas' | 'utah' | 'vermont' | 'virginia' | 'washington' | 'west_virginia' | 'wisconsin' | 'wyoming' | 'district_of_columbia' | 'puerto_rico' | 'virgin_islands' | 'guam' | 'northern_mariana_islands' | 'american_samoa' — US States enum matching Prisma @map values - `zip` string, nullable - `workflow_stage_id` string, nullable - `assigned_user_id` string, nullable - `location_id` string, nullable - `organization_id` string, nullable - `created_from` 'form' | 'call' | 'api' | 'file' | 'sms' | 'fax' | 'chat_agent' | 'manual' | 'bulk_import' | 'eligibility' | 'prior_auth' — Patient creation source enum matching Prisma - `active` boolean - `version` integer - `first_communication_at` string, nullable - `custom_fields` object, nullable - `comments` string, nullable - `tags` Tag[], nullable - `id` string, required - `name` string, required - `workflow_stage` WorkflowStageSummary — Lightweight workflow stage for patient expansion responses. - `id` string, uuid, required - `title` string, nullable - `actions` WorkflowStageAction[], nullable - `order` integer, nullable - `description` string, nullable - `assigned_user` UserSummary - `id` string, required - `name` string, nullable - `email` string, nullable - `referrals` ReferralResponse[], nullable - `id` string, uuid, required - `physician_name` string, nullable - `physician_email` string, nullable - `physician_phone` string, nullable - `physician_fax` string, nullable - `physician_group` string, nullable - `physician_npi` string, nullable - `physician_address` string, nullable - `physician_address_2` string, nullable - `physician_city` string, nullable - `physician_state` 'alabama' | 'alaska' | 'arizona' | 'arkansas' | 'california' | 'colorado' | 'connecticut' | 'delaware' | 'florida' | 'georgia' | 'hawaii' | 'idaho' | 'illinois' | 'indiana' | 'iowa' | 'kansas' | 'kentucky' | 'louisiana' | 'maine' | 'maryland' | 'massachusetts' | 'michigan' | 'minnesota' | 'mississippi' | 'missouri' | 'montana' | 'nebraska' | 'nevada' | 'new_hampshire' | 'new_jersey' | 'new_mexico' | 'new_york' | 'north_carolina' | 'north_dakota' | 'ohio' | 'oklahoma' | 'oregon' | 'pennsylvania' | 'rhode_island' | 'south_carolina' | 'south_dakota' | 'tennessee' | 'texas' | 'utah' | 'vermont' | 'virginia' | 'washington' | 'west_virginia' | 'wisconsin' | 'wyoming' | 'district_of_columbia' | 'puerto_rico' | 'virgin_islands' | 'guam' | 'northern_mariana_islands' | 'american_samoa' — US States enum matching Prisma @map values - `physician_zip` string, nullable - `icd_codes` string[], nullable - `service_types` ServiceType[], nullable - `start_date` string, date, nullable - `end_date` string, date, nullable - `location_id` string, nullable - `created_at` string, date-time, nullable - `updated_at` string, date-time, nullable - `payors` Payor[], nullable - `id` string, uuid, required - `created_at` string, nullable, required - `updated_at` string, nullable, required - `patient_id` string, required - `insurance_id` string, required - `insurance_display_name` string, nullable - `subscriber_id` string, nullable - `relationship_to_subscriber` 'spouse' | 'self' | 'child' | 'employee' | 'unknown' | 'organ_donor' | 'cadaver_donor' | 'life_partner' | 'other_relationship' — Relationship to subscriber enum matching Prisma @map values - `insured_member_id` string, nullable - `group_number` string, nullable - `group_description` string, nullable - `medicaid_id` string, nullable - `payor_responsibility` 'primary' | 'secondary' | 'tertiary' | 'quaternary' — Insurance tier enum matching Prisma - `coverage_from` string, nullable - `coverage_to` string, nullable - `provider_network_status` 'unknown' | 'in_network' | 'out_of_network' — Provider network status enum matching Prisma @map values - `cbh_status` 'active' | 'inactive' — CBH (Community Behavioral Health) coverage status matching Prisma @map values. Captured per-payor; the checklist counterpart is VerificationRequirement.ASK_FOR_CBH. - `plan_funding_type` 'fully_funded' | 'self_funded' | 'unknown' — Plan funding type enum matching Prisma @map values - `plan_name` string, nullable - `plan_type` '01' | '02' | '03' | '12' | '13' | '14' | '15' | '16' | '17' | '18' | '19' | '41' | '42' | '43' | '47' | '48' | '49' | 'AP' | 'C1' | 'CO' | 'CP' | 'D' | 'DB' | 'EP' | 'FF' | 'GP' | 'HB' | 'HD' | 'HG' | 'HM' | 'HN' | 'HP' | 'HS' | 'IN' | 'IP' | 'LC' | 'LD' | 'LI' | 'LT' | 'M' | 'MA' | 'MB' | 'MC' | 'MD' | 'ME' | 'MH' | 'MI' | 'MJ' | 'MK' | 'ML' | 'MM' | 'MN' | 'MO' | 'MP' | 'MR' | 'MT' | 'OA' | 'OT' | 'PE' | 'PL' | 'PP' | 'PR' | 'PS' | 'QM' | 'RP' | 'SA' | 'SP' | 'TF' | 'WC' | 'WU' — Insurance plan type enum matching Prisma - X12 standard codes - `plan_renewal_date_type` 'calendar_year' | 'service_year' | 'contract' — Plan renewal date type enum matching Prisma @map values - `cob_on_file` 'not_required' | 'pending' | 'complete' — COB status enum matching Prisma @map values - `cob_notes` string, nullable - `cob_last_verified_at` string, nullable - `has_other_active_coverage` boolean, nullable - `out_of_state_benefits` boolean, nullable - `out_of_state_benefits_comments` string, nullable - `in_grace_period` boolean, nullable - `last_payment_date` string, nullable - `is_cobra_coverage` boolean, nullable - `deductible_apply_to_oop` boolean, nullable - `copay_applies_to_oop_max` boolean, nullable - `eligibility_check_status` 'active' | 'inactive' | 'pending' | 'failed' — Eligibility check status enum matching Prisma EligibilityStatus. Note: this Python enum has `FAILED` but the Postgres `eligibility_check_status` type does not — pre-existing drift between Prisma and the DB. Don't use `pg_enum(EligibilityStatus)` for the DB column; declare the column with the DB's actual values via a literal `ENUM(...)`. - `eligibility_check_comment` string, nullable - `eligibility_check_date` string, nullable - `eligibility_version` integer - `individual_deductible_policy_in_network` number, nullable - `individual_deductible_policy_out_network` number, nullable - `individual_deductible_remaining_in_network` number, nullable - `individual_deductible_remaining_out_network` number, nullable - `family_deductible_policy_in_network` number, nullable - `family_deductible_policy_out_network` number, nullable - `family_deductible_remaining_in_network` number, nullable - `family_deductible_remaining_out_network` number, nullable - `individual_oop_max_policy_in_network` number, nullable - `individual_oop_max_policy_out_network` number, nullable - `individual_oop_max_remaining_in_network` number, nullable - `individual_oop_max_remaining_out_network` number, nullable - `family_oop_max_policy_in_network` number, nullable - `family_oop_max_policy_out_network` number, nullable - `family_oop_max_remaining_in_network` number, nullable - `family_oop_max_remaining_out_network` number, nullable - `benefits_related_entities` object[], nullable - `ai_summary` string, nullable - `ai_summary_generated_at` string, nullable - `patient` object, nullable - `insurance` object, nullable - `subscriber` object, nullable - `services` PayorService[], nullable - `id` string, uuid, required - `payor_id` string, required - `service_type` 'medical_care' | 'surgical' | 'consultation' | 'diagnostic_x_ray' | 'diagnostic_lab' | 'radiation_therapy' | 'anesthesia' | 'surgical_assistance' | 'other_medical' | 'blood_charges' | 'used_durable_medical_equipment' | 'durable_medical_equipment_purchase' | 'ambulatory_service_center_facility' | 'renal_supplies_in_home' | 'alternate_method_dialysis' | 'chronic_renal_disease_equipment' | 'pre_admission_testing' | 'durable_medical_equipment_rental' | 'pneumonia_vaccine' | 'second_surgical_opinion' | 'third_surgical_opinion' | 'social_work' | 'diagnostic_dental' | 'periodontics' | 'restorative' | 'endodontics' | 'maxillofacial_prosthetics' | 'adjunctive_dental_services' | 'health_benefit_plan_coverage' | 'plan_waiting_period' | 'chiropractic' | 'chiropractic_office_visits' | 'dental_care' | 'dental_crowns' | 'dental_accident' | 'orthodontics' | 'prosthodontics' | 'oral_surgery' | 'routine_preventive_dental' | 'home_health_care' | 'home_health_prescriptions' | 'home_health_visits' | 'hospice' | 'respite_care' | 'hospital' | 'hospital_inpatient' | 'hospital_room_and_board' | 'hospital_outpatient' | 'hospital_emergency_accident' | 'hospital_emergency_medical' | 'hospital_ambulatory_surgical' | 'long_term_care' | 'major_medical' | 'medically_related_transportation' | 'air_transportation' | 'cabulance' | 'licensed_ambulance' | 'general_benefits' | 'in_vitro_fertilization' | 'mri_cat_scan' | 'donor_procedures' | 'acupuncture' | 'newborn_care' | 'pathology' | 'smoking_cessation' | 'well_baby_care' | 'maternity' | 'transplants' | 'audiology_exam' | 'inhalation_therapy' | 'diagnostic_medical' | 'private_duty_nursing' | 'prosthetic_device' | 'dialysis' | 'otological_exam' | 'chemotherapy' | 'allergy_testing' | 'immunizations' | 'routine_physical' | 'family_planning' | 'infertility' | 'abortion' | 'aids' | 'emergency_services' | 'cancer' | 'pharmacy' | 'free_standing_prescription_drug' | 'mail_order_prescription_drug' | 'brand_name_prescription_drug' | 'generic_prescription_drug' | 'podiatry' | 'podiatry_office_visits' | 'podiatry_nursing_home_visits' | 'professional_physician' | 'anesthesiologist' | 'professional_visit_office' | 'professional_visit_inpatient' | 'professional_visit_outpatient' | 'professional_visit_nursing_home' | 'professional_visit_skilled_nursing_facility' | 'professional_visit_home' | 'psychiatric' | 'psychiatric_room_and_board' | 'psychotherapy' | 'psychiatric_inpatient' | 'psychiatric_outpatient' | 'rehabilitation' | 'rehabilitation_room_and_board' | 'rehabilitation_inpatient' | 'rehabilitation_outpatient' | 'occupational_therapy' | 'physical_medicine' | 'speech_therapy' | 'skilled_nursing_care' | 'skilled_nursing_care_room_and_board' | 'substance_abuse' | 'alcoholism' | 'drug_addiction' | 'vision_optometry' | 'frames' | 'routine_exam' | 'lenses' | 'nonmedically_necessary_physical' | 'experimental_drug_therapy' | 'burn_care' | 'brand_name_prescription_drug_formulary' | 'brand_name_prescription_drug_non_formulary' | 'independent_medical_evaluation' | 'partial_hospitalization_psychiatric' | 'day_care_psychiatric' | 'cognitive_therapy' | 'massage_therapy' | 'pulmonary_rehabilitation' | 'cardiac_rehabilitation' | 'pediatric' | 'nursery' | 'skin' | 'orthopedic' | 'cardiac' | 'lymphatic' | 'gastrointestinal' | 'endocrine' | 'neurology' | 'eye' | 'invasive_procedures' | 'gynecological' | 'obstetrical' | 'obstetrical_gynecological' | 'mail_order_prescription_drug_brand_name' | 'mail_order_prescription_drug_generic' | 'physician_visit_office_sick' | 'physician_visit_office_well' | 'coronary_care' | 'private_duty_nursing_inpatient' | 'private_duty_nursing_home' | 'surgical_benefits_professional' | 'surgical_benefits_facility' | 'mental_health_provider_inpatient' | 'mental_health_provider_outpatient' | 'mental_health_facility_inpatient' | 'mental_health_facility_outpatient' | 'substance_abuse_facility_inpatient' | 'substance_abuse_facility_outpatient' | 'screening_x_ray' | 'screening_laboratory' | 'mammogram_high_risk_patient' | 'mammogram_low_risk_patient' | 'flu_vaccination' | 'eyewear_and_accessories' | 'case_management' | 'dermatology' | 'durable_medical_equipment' | 'diabetic_supplies' | 'generic_prescription_drug_formulary' | 'generic_prescription_drug_non_formulary' | 'allergy' | 'intensive_care' | 'mental_health' | 'neonatal_intensive_care' | 'oncology' | 'physical_therapy' | 'pulmonary' | 'renal' | 'residential_psychiatric_treatment' | 'transitional_care' | 'transitional_nursery_care' | 'urgent_care', required — X12 Service Type — human-readable enum values stored in the database. See app/utils/service_type_mapping.py for code-to-type mappings. - `created_at` string, nullable, required - `updated_at` string, nullable, required - `verification_benefits_status` 'completed' | 'pending' | 'in_progress' — Verification benefits status enum matching Prisma @map values - `verification_dates` string[], nullable - `verification_user_ids` string[], nullable - `verification_benefits_comment` string, nullable - `pre_cert_name` string, nullable - `pre_cert_phone_number` string, nullable - `pre_cert_fax` string, nullable - `pre_cert_url` string, nullable - `pre_cert_penalty` string, nullable - `pre_cert_email` string, nullable - `sca_instructions` string, nullable - `claim_address` string, nullable - `oon_reimbursement_rate` number, nullable - `oon_reimbursement_rate_type` 'ucr' | 'medicare' | 'mnrp' | 'maa' | 'billed_charges' | 'fee_schedule' | 'mrc1' | 'mrc2' | 'local_allowable_rates' — OON Reimbursement rate type enum matching Prisma @map values - `eligibility_check_id` string, nullable - `carve_out_insurer_id` string, nullable - `location_id` string, nullable - `rep_name` string, nullable - `call_reference_notes` string, nullable - `covered_cpt_codes` string[], nullable - `not_covered_cpt_codes` string[], nullable - `covered_icd_codes` string[], nullable - `not_covered_icd_codes` string[], nullable - `version` integer - `location_rates` PayorServiceLocation[], nullable - `service_location` 'standard' | 'home' | 'office' | 'school' | 'daycare' | 'community' | 'telehealth', required — Service location enum matching Prisma @@map("service_location"). - `covered_in_network` boolean, nullable — Whether service is covered in network - `covered_out_network` boolean, nullable — Whether service is covered out of network - `copay_in_network` number, nullable — Copay in network - `copay_out_network` number, nullable — Copay out of network - `co_insurance_in_network` number, nullable — Co-insurance in network (percentage) - `co_insurance_out_network` number, nullable — Co-insurance out of network (percentage) - `auth_required_in_network` boolean, nullable — Whether authorization is required in network - `auth_required_out_network` boolean, nullable — Whether authorization is required out of network - `auth_required_at_visit_in_network` integer, nullable — Visit number from which authorization is required in network - `auth_required_at_visit_out_network` integer, nullable — Visit number from which authorization is required out of network - `mnr_required_in_network` boolean, nullable — Whether a medical necessity review is required in network - `mnr_required_out_network` boolean, nullable — Whether a medical necessity review is required out of network - `mnr_required_at_visit_in_network` integer, nullable — Visit number from which a medical necessity review is required in network - `mnr_required_at_visit_out_network` integer, nullable — Visit number from which a medical necessity review is required out of network - `deductible_apply_in_network` boolean, nullable — Whether deductible applies in network - `deductible_apply_out_network` boolean, nullable — Whether deductible applies out of network - `oop_apply_in_network` boolean, nullable — Whether OOP applies in network - `oop_apply_out_network` boolean, nullable — Whether OOP applies out of network - `dollar_limit_in_network` number, nullable — Dollar limit in network - `dollar_limit_out_network` number, nullable — Dollar limit out of network - `dollar_limit_remaining_in_network` number, nullable — Dollar limit remaining in network - `dollar_limit_remaining_out_network` number, nullable — Dollar limit remaining out of network - `dollar_limit_time_period_in_network` 'daily' | 'monthly' | 'annually' — Periodic maximum time period enum matching Prisma - `dollar_limit_time_period_out_network` 'daily' | 'monthly' | 'annually' — Periodic maximum time period enum matching Prisma - `dollar_limit_type_in_network` 'soft' | 'hard' — Limit type enum matching Prisma @map values - `dollar_limit_type_out_network` 'soft' | 'hard' — Limit type enum matching Prisma @map values - `visit_limit_in_network` number, nullable — Visit limit in network - `visit_limit_out_network` number, nullable — Visit limit out of network - `visit_limit_remaining_in_network` number, nullable — Visit limit remaining in network - `visit_limit_remaining_out_network` number, nullable — Visit limit remaining out of network - `visit_limit_time_period_in_network` 'daily' | 'monthly' | 'annually' — Periodic maximum time period enum matching Prisma - `visit_limit_time_period_out_network` 'daily' | 'monthly' | 'annually' — Periodic maximum time period enum matching Prisma - `visit_limit_type_in_network` 'soft' | 'hard' — Limit type enum matching Prisma @map values - `visit_limit_type_out_network` 'soft' | 'hard' — Limit type enum matching Prisma @map values - `id` string, required - `payor_service_id` string, required - `created_at` string, nullable, required - `updated_at` string, nullable, required - `version` integer - `payor` object, nullable - `active` boolean - `version` integer - `external_id_values` ExternalIdValueResponse[], nullable - `id` string, uuid, required - `patient_id` string, uuid, required - `value` string, required - `external_id_type` ExternalIdTypeSummary, required — Read-only summary of an external_id_types row. Used embedded in `ExternalIdValueResponse` (where `created_at` stays None) and as the body of `GET /v1/external-id-types` (where it's populated). - `id` string, uuid, required - `name` string, required - `created_at` string, date-time, nullable - `created_at` string, date-time, required - `updated_at` string, date-time, required - `pagination` Pagination, required — Pagination information for list responses. Fields: - has_more: Whether more items exist beyond this page - total: Total number of items across all pages - page: Current page number (1-based) - limit: Number of items per page - `has_more` boolean, required - `total` integer, required - `page` integer, required - `limit` integer, required ## Other responses - `422` — Validation Error --- [API](https://skmtc.net/getsolum/apis/solum-health-api.md) · [All operations](https://skmtc.net/getsolum/apis/solum-health-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/getsolum/solum-health-api/versions/2bf886cdf729/schema)