---
title: "Update Patient"
method: PATCH
path: "/v1/patients/{id}"
tags: ["Patients"]
---

# Update Patient

`PATCH /v1/patients/{id}`

## Path parameters

- `id` string, uuid, required

## Query parameters

- `expand[]` PatientExpand[], nullable — Fields to expand in the response

## Request body

- PatientUpdateRequest — Request model for updating a patient with optimistic locking
  - `first_name` string, nullable — Patient's first name
  - `middle_name` string, nullable — Patient's middle name
  - `last_name` string, nullable — Patient's last name
  - `phone_number` string, nullable — Patient's phone number
  - `additional_phone_number` string, nullable — Patient's additional phone number
  - `email` string, nullable — Patient's email address
  - `date_of_birth` string, date, nullable — Patient's date of birth (YYYY-MM-DD, MM/DD/YYYY, YYYYMMDD)
  - `gender` 'male' | 'female' | 'other' — Gender enum matching Prisma
  - `address` string, nullable — Patient's street address
  - `address2` string, nullable — Patient's address line 2
  - `city` string, nullable — Patient's city
  - `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 — Patient's ZIP code
  - `workflow_stage_id` string, nullable — Workflow stage ID or stage name
  - `assigned_user_id` string, nullable — User ID or user email
  - `location_id` string, nullable — Company location ID (null clears the location)
  - `organization_id` string, nullable — Company organization ID (null clears the organization)
  - `active` boolean, nullable — Patient active status
  - `custom_fields` object, nullable — Custom fields as key-value pairs
  - `comments` string, nullable — Patient comments
  - `tags` string[], nullable — Tag IDs or names (replaces existing tags)
  - `add_tags` string[], nullable — Tag IDs or names to add without removing existing
  - `remove_tags` string[], nullable — Tag IDs or names to remove
  - `referral` ReferralCreateRequest — Nested referral creation for patient creation
    - `physician_name` string, nullable — Referring physician's name
    - `physician_email` string, nullable — Referring physician's email
    - `physician_phone` string, nullable — Referring physician's phone
    - `physician_fax` string, nullable — Referring physician's fax
    - `physician_group` string, nullable — Referring physician's group/practice
    - `physician_npi` string, nullable — Referring physician's National Provider Identifier
    - `physician_address` string, nullable — Referring physician's street address
    - `physician_address_2` string, nullable — Referring physician's address line 2
    - `physician_city` string, nullable — Referring physician's city
    - `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 — Referring physician's ZIP code
    - `icd_codes` string[], nullable — ICD diagnosis codes
    - `service_types` ServiceType[], nullable — Service types for the referral
    - `start_date` string, date, nullable — Referral start date (YYYY-MM-DD)
    - `end_date` string, date, nullable — Referral end date (YYYY-MM-DD)
    - `location_id` string, nullable — Company location ID
    - `file_id` string, nullable — Source file ID — set when the referral originates from a document extraction so the UI can link back to the file.
  - `payors` PayorUpdateInline[], nullable — Payors to create/update with the patient
    - `payor_id` string, nullable — ID of existing payor to update (if provided, this is an update)
    - `insurance_id` string, nullable — Insurance ID for this payor (required for create)
    - `insurance_display_name` string, nullable — Chosen plan display name; must be one of the insurance's aliases
    - `payor_responsibility` 'primary' | 'secondary' | 'tertiary' | 'quaternary' — Insurance tier enum matching Prisma
    - `insured_member_id` string, nullable — Member ID for this insurance
    - `group_number` string, nullable — Group number for the insurance plan
    - `group_description` string, nullable — Group description for the insurance plan
    - `relationship_to_subscriber` 'spouse' | 'self' | 'child' | 'employee' | 'unknown' | 'organ_donor' | 'cadaver_donor' | 'life_partner' | 'other_relationship' — Relationship to subscriber enum matching Prisma @map values
    - `coverage_from` string, date, nullable — Coverage start date (YYYY-MM-DD)
    - `coverage_to` string, date, nullable — Coverage end date (YYYY-MM-DD)
    - `provider_network_status` 'unknown' | 'in_network' | 'out_of_network' — Provider network status enum matching Prisma @map values
    - `plan_funding_type` 'fully_funded' | 'self_funded' | 'unknown' — Plan funding type enum matching Prisma @map values
    - `plan_name` string, nullable — Insurance plan name
    - `plan_type` string, nullable — Insurance plan type code
    - `eligibility_check_comment` string, nullable — Eligibility check comment
    - `subscriber` SubscriberUpdateInline — Inline subscriber update for payor endpoints (all fields optional)
      - `first_name` string, nullable — Subscriber's first name
      - `last_name` string, nullable — Subscriber's last name
      - `middle_name` string, nullable — Subscriber's middle name
      - `dob` string, date-time, nullable — Subscriber's date of birth
      - `gender` 'male' | 'female' | 'other' — Gender enum matching Prisma
      - `insured_member_id` string, nullable — Subscriber's member ID
      - `address` string, nullable — Subscriber's address
      - `address2` string, nullable — Subscriber's address line 2
      - `city` string, nullable — Subscriber's city
      - `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 — Subscriber's ZIP code
      - `version` integer, nullable — Version for optimistic locking
    - `subscriber_id` string, nullable — Existing subscriber ID
    - `services` PayorServiceCreateInline[], nullable — Payor services to create/replace for this payor
      - `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.
      - `verification_benefits_status` 'completed' | 'pending' | 'in_progress' — Verification benefits status enum matching Prisma @map values
      - `verification_dates` string[], nullable — List of verification dates
      - `verification_benefits_comment` string, nullable — Verification benefits comment
      - `pre_cert_name` string, nullable — Pre-certification contact name
      - `pre_cert_phone_number` string, nullable — Pre-certification phone number
      - `pre_cert_fax` string, nullable — Pre-certification fax number
      - `pre_cert_url` string, nullable — Pre-certification URL/portal
      - `pre_cert_penalty` string, nullable — Penalty if pre-cert not obtained
      - `pre_cert_email` string, nullable — Pre-certification email address
      - `sca_instructions` string, nullable — Single Case Agreement instructions
      - `claim_address` string, nullable — Address where claims should be submitted
      - `oon_reimbursement_rate` number, nullable — Out-of-network reimbursement rate percentage
      - `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 — Clearinghouse eligibility check ID for tracking
      - `carve_out_insurer_id` string, nullable — Carve-out insurer ID for behavioral health
      - `location_id` string, nullable — Company location ID reference
      - `rep_name` string, nullable — Insurance representative name
      - `call_reference_notes` string, nullable — Call reference notes
      - `location_rates` PayorServiceLocationCreate[], nullable — Location-specific copay, coinsurance, and telehealth rates
        - `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, nullable — Optional ID for updates (if omitted, creates new)
  - `version` integer, nullable — Current version number for optimistic locking

## Response `200`

Successful Response

- Patient — Patient resource response model.
  - `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

## 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)