---
title: "Get Recording Details"
method: GET
path: "/api/v1/recordings/{recording_id}"
tags: ["include_in_client_gen"]
---

# Get Recording Details

`GET /api/v1/recordings/{recording_id}`

## Request

- Base URL: `https://app.sagecare.ai` (the document declares no server; this is the origin it was published from)
- URL: `https://app.sagecare.ai/api/v1/recordings/{recording_id}`
- Auth: API key in header `X-Session-Token`

Get recording details by ID.

Returns recording information including associated patient/contact/user,
processing status, and post-hoc actions.

## Path parameters

- `recording_id` integer, required

## Response `200`

OK

- RecordingDetailsResponse: Detailed recording information including processing status.
  - `id` integer, required
  - `audio_file_url` string, required
  - `duration_seconds` integer, required
  - `patient_id` integer
  - `contact_id` integer
  - `uploaded_by_id` integer
  - `organization_id` integer, required
  - `created_at` string, date-time, required
  - `updated_at` string, date-time, required
  - `summary` string
  - `description` string
  - `patient` Subject
    - `id` integer, required
    - `name` string, required
  - `contact` Subject
    - `id` integer, required
    - `name` string, required
  - `uploaded_by` Subject
    - `id` integer, required
    - `name` string, required
  - `post_recording_processing` PostHocProcessing, required
    - `overall_status` union, required
      - 'pending' | 'initializing' | 'processing' | 'complete' | 'failed'
      - string
    - `actions` PostHocActions, required
      - `call_description` PostHocDescriptionDetail
        - `id` integer, required
        - `status` union, required
          - 'in_progress' | 'blocked' | 'failed' | 'proposed' | 'accepted' | 'declined' | 'cancelled'
          - string
        - `started_at` string, date-time, required
        - `finished_at` string, date-time
        - `blocked_on_action_ids` integer[]
        - `result` integer
        - `display_title` string: AI-generated conversational headline for the suggestion, e.g. "Add John as a client". Empty on actions proposed before generated copy shipped and on internal enrichment actions — fall back to the action type label.
        - `display_reason` string: AI-generated one-line reason grounded in the conversation, e.g. "He mentioned he moved to Ridgewood Rd last month." Empty on actions proposed before generated copy shipped and on internal enrichment actions.
        - `proposal` DescriptionResult
          - `description` string, required
      - `call_summary` PostHocSummaryDetail
        - `id` integer, required
        - `status` union, required
          - 'in_progress' | 'blocked' | 'failed' | 'proposed' | 'accepted' | 'declined' | 'cancelled'
          - string
        - `started_at` string, date-time, required
        - `finished_at` string, date-time
        - `blocked_on_action_ids` integer[]
        - `result` integer
        - `display_title` string: AI-generated conversational headline for the suggestion, e.g. "Add John as a client". Empty on actions proposed before generated copy shipped and on internal enrichment actions — fall back to the action type label.
        - `display_reason` string: AI-generated one-line reason grounded in the conversation, e.g. "He mentioned he moved to Ridgewood Rd last month." Empty on actions proposed before generated copy shipped and on internal enrichment actions.
        - `proposal` SummaryResult
          - `summary` string, required
      - `follow_up_email` PostHocEmailDetail
        - `id` integer, required
        - `status` union, required
          - 'in_progress' | 'blocked' | 'failed' | 'proposed' | 'accepted' | 'declined' | 'cancelled'
          - string
        - `started_at` string, date-time, required
        - `finished_at` string, date-time
        - `blocked_on_action_ids` integer[]
        - `result` integer
        - `display_title` string: AI-generated conversational headline for the suggestion, e.g. "Add John as a client". Empty on actions proposed before generated copy shipped and on internal enrichment actions — fall back to the action type label.
        - `display_reason` string: AI-generated one-line reason grounded in the conversation, e.g. "He mentioned he moved to Ridgewood Rd last month." Empty on actions proposed before generated copy shipped and on internal enrichment actions.
        - `proposal` EmailDraft
          - `subject` string, required: Brief, professional email subject line
          - `body` string, required: Concise, polite email body. Include only facts from the transcript—no invented details. Reference the phone conversation, include clear next steps.
          - `to` string, email: Recipient email address: one stated in the communication, or the recipient's stored address from their record (fetch_contact_details, fetch_client_details, fetch_referrer_details). Set to null only when neither has one. Never invent an email address.
          - `cc` string, email
          - `bcc` string, email
        - `signature_managed` boolean
        - `attachments` SentEmailAttachment[]
          - `id` integer, required
          - `filename` string, required
          - `content_type` string, required
          - `size_bytes` integer, required
          - `size_label` string, required
          - `type_label` string, required
          - `icon` string, required
          - `unavailable` boolean, required
          - `download_url` string
        - `is_sent` boolean
        - `sent_at` string, date-time, nullable
        - `sent_email` SentFollowUpEmail: The latest email that Sage sent for a follow-up action.
          - `subject` string, required
          - `body` string, required
          - `body_html` string
          - `to` string, nullable
          - `cc` string, nullable
          - `bcc` string, nullable
          - `sent_at` string, date-time, required
          - `provider_label` string, required
          - `attachments` SentEmailAttachment[], required
            - `id` integer, required
            - `filename` string, required
            - `content_type` string, required
            - `size_bytes` integer, required
            - `size_label` string, required
            - `type_label` string, required
            - `icon` string, required
            - `unavailable` boolean, required
            - `download_url` string
      - `create_patient` PostHocCreatePatientDetail
        - `id` integer, required
        - `status` union, required
          - 'in_progress' | 'blocked' | 'failed' | 'proposed' | 'accepted' | 'declined' | 'cancelled'
          - string
        - `started_at` string, date-time, required
        - `finished_at` string, date-time
        - `blocked_on_action_ids` integer[]
        - `result` integer
        - `display_title` string: AI-generated conversational headline for the suggestion, e.g. "Add John as a client". Empty on actions proposed before generated copy shipped and on internal enrichment actions — fall back to the action type label.
        - `display_reason` string: AI-generated one-line reason grounded in the conversation, e.g. "He mentioned he moved to Ridgewood Rd last month." Empty on actions proposed before generated copy shipped and on internal enrichment actions.
        - `proposal` NewPatient
          - `first_name` string, required
          - `last_name` string, required
          - `emails` Email[]
            - `email_type` union
              - …
            - `email` string, email, required
          - `phone_numbers` PhoneNumber[]
            - `phone_type` union, required
              - …
            - `number` string, required: US phone number
          - `addresses` Address[]
            - `address_type` union, required
              - …
            - `address_line1` string
            - `address_line2` string
            - `city` string
            - `state` union
              - …
            - `zip_code` union
              - …
          - `gender` 'male' | 'female' | 'unknown': Centralized gender choices for care models
          - `birth_date` string, date
          - `organization_id` integer, required
          - `post_hoc_action_id` integer
      - `update_patient` PostHocUpdatePatientDetail
        - `id` integer, required
        - `status` union, required
          - 'in_progress' | 'blocked' | 'failed' | 'proposed' | 'accepted' | 'declined' | 'cancelled'
          - string
        - `started_at` string, date-time, required
        - `finished_at` string, date-time
        - `blocked_on_action_ids` integer[]
        - `result` integer
        - `display_title` string: AI-generated conversational headline for the suggestion, e.g. "Add John as a client". Empty on actions proposed before generated copy shipped and on internal enrichment actions — fall back to the action type label.
        - `display_reason` string: AI-generated one-line reason grounded in the conversation, e.g. "He mentioned he moved to Ridgewood Rd last month." Empty on actions proposed before generated copy shipped and on internal enrichment actions.
        - `proposal` UpdatePatientProposal: Stored UPDATE_PATIENT post hoc action proposal: partial patient changes plus a reference to the patient they apply to.
          - `post_hoc_action_id` integer
          - `first_name` string
          - `last_name` string
          - `emails` Email[]
            - `email_type` union
              - …
            - `email` string, email, required
          - `phone_numbers` PhoneNumber[]
            - `phone_type` union, required
              - …
            - `number` string, required: US phone number
          - `addresses` Address[]
            - `address_type` union, required
              - …
            - `address_line1` string
            - `address_line2` string
            - `city` string
            - `state` union
              - …
            - `zip_code` union
              - …
          - `gender` 'male' | 'female' | 'unknown': Centralized gender choices for care models
          - `birth_date` string, date
          - `status` 'prospect' | 'closed_lost' | 'active' | 'churned'
          - `description` string
          - `patient_id` integer, required
          - `organization_id` integer
      - `create_contact` PostHocCreateContactDetail
        - `id` integer, required
        - `status` union, required
          - 'in_progress' | 'blocked' | 'failed' | 'proposed' | 'accepted' | 'declined' | 'cancelled'
          - string
        - `started_at` string, date-time, required
        - `finished_at` string, date-time
        - `blocked_on_action_ids` integer[]
        - `result` integer
        - `display_title` string: AI-generated conversational headline for the suggestion, e.g. "Add John as a client". Empty on actions proposed before generated copy shipped and on internal enrichment actions — fall back to the action type label.
        - `display_reason` string: AI-generated one-line reason grounded in the conversation, e.g. "He mentioned he moved to Ridgewood Rd last month." Empty on actions proposed before generated copy shipped and on internal enrichment actions.
        - `proposal` NewContact
          - `first_name` string, required
          - `last_name` string, required
          - `emails` Email[]
            - `email_type` union
              - …
            - `email` string, email, required
          - `phone_numbers` PhoneNumber[]
            - `phone_type` union, required
              - …
            - `number` string, required: US phone number
          - `addresses` Address[]
            - `address_type` union, required
              - …
            - `address_line1` string
            - `address_line2` string
            - `city` string
            - `state` union
              - …
            - `zip_code` union
              - …
          - `gender` 'male' | 'female' | 'unknown': Centralized gender choices for care models
          - `birth_date` string, date
          - `organization_id` integer, required
          - `post_hoc_action_id` integer
      - `update_contact` PostHocUpdateContactDetail
        - `id` integer, required
        - `status` union, required
          - 'in_progress' | 'blocked' | 'failed' | 'proposed' | 'accepted' | 'declined' | 'cancelled'
          - string
        - `started_at` string, date-time, required
        - `finished_at` string, date-time
        - `blocked_on_action_ids` integer[]
        - `result` integer
        - `display_title` string: AI-generated conversational headline for the suggestion, e.g. "Add John as a client". Empty on actions proposed before generated copy shipped and on internal enrichment actions — fall back to the action type label.
        - `display_reason` string: AI-generated one-line reason grounded in the conversation, e.g. "He mentioned he moved to Ridgewood Rd last month." Empty on actions proposed before generated copy shipped and on internal enrichment actions.
        - `proposal` UpdateContactProposal: Stored UPDATE_CONTACT post hoc action proposal: partial contact changes plus a reference to the contact they apply to.
          - `post_hoc_action_id` integer
          - `first_name` string
          - `last_name` string
          - `emails` Email[]
            - `email_type` union
              - …
            - `email` string, email, required
          - `phone_numbers` PhoneNumber[]
            - `phone_type` union, required
              - …
            - `number` string, required: US phone number
          - `addresses` Address[]
            - `address_type` union, required
              - …
            - `address_line1` string
            - `address_line2` string
            - `city` string
            - `state` union
              - …
            - `zip_code` union
              - …
          - `gender` 'male' | 'female' | 'unknown': Centralized gender choices for care models
          - `birth_date` string, date
          - `description` string
          - `contact_id` integer, required
          - `organization_id` integer
      - `create_referrer` PostHocCreateReferrerDetail
        - `id` integer, required
        - `status` union, required
          - 'in_progress' | 'blocked' | 'failed' | 'proposed' | 'accepted' | 'declined' | 'cancelled'
          - string
        - `started_at` string, date-time, required
        - `finished_at` string, date-time
        - `blocked_on_action_ids` integer[]
        - `result` integer
        - `display_title` string: AI-generated conversational headline for the suggestion, e.g. "Add John as a client". Empty on actions proposed before generated copy shipped and on internal enrichment actions — fall back to the action type label.
        - `display_reason` string: AI-generated one-line reason grounded in the conversation, e.g. "He mentioned he moved to Ridgewood Rd last month." Empty on actions proposed before generated copy shipped and on internal enrichment actions.
        - `proposal` NewReferrer
          - `first_name` string, required
          - `last_name` string, required
          - `emails` Email[]
            - `email_type` union
              - …
            - `email` string, email, required
          - `phone_numbers` PhoneNumber[]
            - `phone_type` union, required
              - …
            - `number` string, required: US phone number
          - `addresses` Address[]
            - `address_type` union, required
              - …
            - `address_line1` string
            - `address_line2` string
            - `city` string
            - `state` union
              - …
            - `zip_code` union
              - …
          - `organization_id` integer, required
          - `post_hoc_action_id` integer
      - `update_referrer` PostHocUpdateReferrerDetail
        - `id` integer, required
        - `status` union, required
          - 'in_progress' | 'blocked' | 'failed' | 'proposed' | 'accepted' | 'declined' | 'cancelled'
          - string
        - `started_at` string, date-time, required
        - `finished_at` string, date-time
        - `blocked_on_action_ids` integer[]
        - `result` integer
        - `display_title` string: AI-generated conversational headline for the suggestion, e.g. "Add John as a client". Empty on actions proposed before generated copy shipped and on internal enrichment actions — fall back to the action type label.
        - `display_reason` string: AI-generated one-line reason grounded in the conversation, e.g. "He mentioned he moved to Ridgewood Rd last month." Empty on actions proposed before generated copy shipped and on internal enrichment actions.
        - `proposal` UpdateReferrerProposal: Stored UPDATE_REFERRER post hoc action proposal: partial referrer changes plus a reference to the referrer they apply to.
          - `first_name` string, nullable
          - `last_name` string, nullable
          - `description` string, nullable
          - `emails` Email[], nullable
            - `email_type` union
              - …
            - `email` string, email, required
          - `phone_numbers` PhoneNumber[], nullable
            - `phone_type` union, required
              - …
            - `number` string, required: US phone number
          - `addresses` Address[], nullable
            - `address_type` union, required
              - …
            - `address_line1` string
            - `address_line2` string
            - `city` string
            - `state` union
              - …
            - `zip_code` union
              - …
          - `post_hoc_action_id` integer
          - `referrer_id` integer, required
          - `organization_id` integer
      - `create_referrer_institution` PostHocCreateReferrerInstitutionDetail
        - `id` integer, required
        - `status` union, required
          - 'in_progress' | 'blocked' | 'failed' | 'proposed' | 'accepted' | 'declined' | 'cancelled'
          - string
        - `started_at` string, date-time, required
        - `finished_at` string, date-time
        - `blocked_on_action_ids` integer[]
        - `result` integer
        - `display_title` string: AI-generated conversational headline for the suggestion, e.g. "Add John as a client". Empty on actions proposed before generated copy shipped and on internal enrichment actions — fall back to the action type label.
        - `display_reason` string: AI-generated one-line reason grounded in the conversation, e.g. "He mentioned he moved to Ridgewood Rd last month." Empty on actions proposed before generated copy shipped and on internal enrichment actions.
        - `proposal` NewReferrerInstitution
          - `name` string, required
          - `url` string, nullable
          - `emails` Email[]
            - `email_type` union
              - …
            - `email` string, email, required
          - `phone_numbers` PhoneNumber[]
            - `phone_type` union, required
              - …
            - `number` string, required: US phone number
          - `addresses` Address[]
            - `address_type` union, required
              - …
            - `address_line1` string
            - `address_line2` string
            - `city` string
            - `state` union
              - …
            - `zip_code` union
              - …
          - `organization_id` integer, required
          - `post_hoc_action_id` integer
      - `generate_care_plan` PostHocGenerateCarePlanDetail
        - `id` integer, required
        - `status` union, required
          - 'in_progress' | 'blocked' | 'failed' | 'proposed' | 'accepted' | 'declined' | 'cancelled'
          - string
        - `started_at` string, date-time, required
        - `finished_at` string, date-time
        - `blocked_on_action_ids` integer[]
        - `result` integer
        - `display_title` string: AI-generated conversational headline for the suggestion, e.g. "Add John as a client". Empty on actions proposed before generated copy shipped and on internal enrichment actions — fall back to the action type label.
        - `display_reason` string: AI-generated one-line reason grounded in the conversation, e.g. "He mentioned he moved to Ridgewood Rd last month." Empty on actions proposed before generated copy shipped and on internal enrichment actions.
        - `proposal` NewCarePlan: AI-generated care plan sections from phone call. Each field contains markdown-formatted text summary to be manually entered into WellSky. Null fields indicate the section was not discussed during the call.
          - `structured_care_needs` StructuredCareNeeds: Structured care plan data - starting with Care Needs section fields. Maps to CareNeeds model for structured data storage.
            - `initial_contact` string, date: Date of initial contact with patient
            - `start_date` string, date: Desired/actual care start date
            - `prognosis` 'poor' | 'guarded' | 'fair' | 'good' | 'excellent'
            - `care_goals` string: Care goals: a concise markdown bulleted list of the desired outcomes the patient, family, and medical team agreed on. Cover the level of care needed, specific assistance required (bathing, meal prep, medication reminders, ...), what the patient/family hope to achieve, special considerations, and required caregiver qualifications (e.g. CNA, dementia experience). Goals are durable: describe ongoing needs, never specific appointment dates, one-off events, or scheduling logistics.
            - `proposed_schedule` string: Proposed recurring care schedule (e.g., 'Mon-Fri 9am-5pm', '24/7 live-in'). Never one-off events or specific appointment dates.
          - `structured_demographics` StructuredDemographics: Structured demographics data - patient demographic information. Maps to Demographics model for structured data storage.
            - `date_of_birth` string, date: Patient's date of birth
            - `height` string: Patient height, normalized to feet-and-inches like 5'8" (accept forms like '5 foot 8' or 'five eight')
            - `weight` integer: Patient weight in pounds
            - `date_of_death` string, date: Date of death if applicable
            - `gender` 'male' | 'female': Gender choices for Demographics (separate from Person.Gender)
            - `marital_status` 'married' | 'cohabitating' | 'domestic_partnership' | 'single' | 'separated' | 'divorced' | 'widowed': Marital status choices
            - `spouse_name` string: Spouse or partner name
            - `lives_with` string: Very concise description of living arrangements. One short sentence, 10 words or fewer (e.g., 'alone', 'with daughter', 'with spouse and adult son').
            - `religion` 'christianity' | 'judaism' | 'buddhism' | 'islam' | 'hinduism' | 'other' | 'unaffiliated': Religion choices
            - `attends_services` 'unknown' | 'yes' | 'no': Religious service attendance
            - `dnr` boolean: Do Not Resuscitate status (true=Yes, false=No, null=Unknown). Set only when explicitly discussed ('has a DNR', 'no DNR', 'DNR in place').
            - `languages` Language[]: Languages spoken by patient. Default to ['english'] for a patient in the US when not discussed.
            - `past_profession` string: Previous occupation or profession
          - `structured_medical_conditions` StructuredMedicalConditions: Structured medical conditions data - patient medical conditions and functional limitations. Maps to MedicalConditions model for structured data storage.
            - `medical_conditions` string: Chronic/acute conditions, hospital stays, etc.
            - `hearing` 'good' | 'poor' | 'deaf': Hearing level choices
            - `hearing_aid` boolean: Uses hearing aid
            - `speech` 'good' | 'poor' | 'none': Speech level choices
            - `vision` 'good' | 'poor' | 'blind': Vision level choices
            - `glasses` boolean: Wears glasses
            - `swallowing` 'good' | 'poor' | 'none': Swallowing level choices
            - `other_conditions` OtherCondition[]: Other medical conditions (smoker, on oxygen, etc.)
            - `functional_limitations` FunctionalLimitation[]: Functional limitations (amputation, incontinence, etc.)
          - `structured_allergies` StructuredAllergies: Structured allergies data - known allergens and related notes. Maps to Allergies model for structured data storage.
            - `allergies` union[]: Known allergens. Prefer a value from the provided allergy list; use a free-text name only for an allergen not on the list. Use ['no_known_allergies_nka'] when the patient is explicitly stated to have no known allergies.
              - …
            - `notes` string: Additional allergy notes
          - `structured_adls` StructuredADLs: Structured ADL (Activities of Daily Living) data. Stored as sparse ADLAssessment rows keyed by dynamic ADLOption.
            - `activities` ADLValue[]: ADL task assessments. Include an entry only for tasks that are part of the care plan; omit tasks that don't apply. Each `key` must be one of the organization's configured ADL option keys.
              - …
          - `structured_iadls` StructuredIADLs: Structured IADL (Instrumental Activities of Daily Living) data. Stored as sparse IADLAssessment rows keyed by dynamic IADLOption.
            - `activities` IADLValue[]: IADL task assessments. Include an entry only for tasks that are part of the care plan; omit tasks that don't apply. Each `key` must be one of the organization's configured IADL option keys.
              - …
          - `structured_match_criteria` StructuredMatchCriteria: Structured match criteria data - caregiver matching preferences. Stored as sparse MatchCriterion rows keyed by dynamic MatchCriterionDimension.
            - `criteria` MatchCriterionValue[]: Caregiver matching preferences. Include an entry only for dimensions that are preferred or required; omit dimensions that are not needed. Include gender or language preferences only when explicitly stated. Each `key` must be one of the organization's configured match criterion dimension keys.
              - …
          - `structured_meals` StructuredMeals: Structured meals data - diet, appetite, meal scheduling, food preferences. Maps to Meals model for structured data storage.
            - `meals_assistance` MealsAssistance[]: Types of meal-related assistance needed (Cooking, Preparation, Feeding)
            - `appetite` union: Patient appetite (Poor/Good)
              - …
            - `diet` union: Diet assessment (Poor Nutrition / Desires Improved Nutrition / Special Diet)
              - …
            - `special_diet` string: Description of any special diet
            - `shopping_by` string: Who does grocery shopping
            - `breakfast_time` string, time: Scheduled breakfast time
            - `lunch_time` string, time: Scheduled lunch time
            - `dinner_time` string, time: Scheduled dinner time
            - `snacks_time` string, time: Scheduled snacks time
            - `meals_other` MealsOther[]: Other meal-related conditions (Swallowing Issues, Encourage Liquids)
            - `favorite_breakfast` string: Favorite breakfast foods
            - `favorite_lunch` string: Favorite lunch foods
            - `favorite_snack` string: Favorite snack foods
            - `favorite_dinner` string: Favorite dinner foods
            - `notes` string: Additional meals-related notes
          - `structured_driving` StructuredDriving: Structured driving data - vehicle arrangement, errands, doctor appointments, notes. Maps to Driving model for structured data storage.
            - `vehicle` Vehicle[]: Vehicle / transportation arrangement (Client Drives, Needs Caregiver)
            - `caregiver_vehicle` union: Whose car the caregiver drives (Aide's Car / Client's Car)
              - …
            - `errands_description` string: Errands the caregiver helps with
            - `doctor_appointment_description` string: Ongoing doctor's-appointment transport needs (e.g. 'monthly cardiology', 'weekly PT'); never specific appointment dates or times
            - `notes` string: Additional driving notes
          - `structured_transfers` StructuredTransfers: Structured transfers data - transfer types, aids used, risks, notes. Maps to Transfers model for structured data storage.
            - `transfer_types` string: How the patient transfers (e.g. stand pivot, two-person assist)
            - `transfer_aides` TransferAide[]: Aids used to help the patient transfer (Gait Belt, Hoyer, Other)
            - `aides_other` string: Description of any other transfer aid (when Other is selected)
            - `transfer_risks` string: Risks associated with transferring the patient
            - `notes` string: Additional transfer notes
          - `structured_equipment` StructuredEquipmentEnvironment: Structured equipment / environment data - in-home equipment, safety, and accessibility. Maps to EquipmentEnvironment model for structured data storage.
            - `safety_assessment_done` boolean: Whether a home safety assessment has been completed
            - `interested_in_lifeline` boolean: Whether the patient is interested in a Lifeline / medical alert system
            - `equipment` EquipmentItem[]: In-home equipment and environment modifications. Use 'other' for an item not on the list and describe it in `equipment_other`.
            - `equipment_other` string: Description of any other equipment or environment modification (when 'other' is selected)
            - `notes` string: Additional equipment / environment notes
          - `patient_id` integer: Patient ID - optional for AI generation, required for API save
          - `post_hoc_action_id` integer: Post hoc action ID - marks the action as complete after care plan creation
      - `update_care_plan` PostHocUpdateCarePlanDetail
        - `id` integer, required
        - `status` union, required
          - 'in_progress' | 'blocked' | 'failed' | 'proposed' | 'accepted' | 'declined' | 'cancelled'
          - string
        - `started_at` string, date-time, required
        - `finished_at` string, date-time
        - `blocked_on_action_ids` integer[]
        - `result` integer
        - `display_title` string: AI-generated conversational headline for the suggestion, e.g. "Add John as a client". Empty on actions proposed before generated copy shipped and on internal enrichment actions — fall back to the action type label.
        - `display_reason` string: AI-generated one-line reason grounded in the conversation, e.g. "He mentioned he moved to Ridgewood Rd last month." Empty on actions proposed before generated copy shipped and on internal enrichment actions.
        - `proposal` UpdateCarePlan
          - `structured_care_needs` StructuredCareNeeds: Structured care plan data - starting with Care Needs section fields. Maps to CareNeeds model for structured data storage.
            - `initial_contact` string, date: Date of initial contact with patient
            - `start_date` string, date: Desired/actual care start date
            - `prognosis` 'poor' | 'guarded' | 'fair' | 'good' | 'excellent'
            - `care_goals` string: Care goals: a concise markdown bulleted list of the desired outcomes the patient, family, and medical team agreed on. Cover the level of care needed, specific assistance required (bathing, meal prep, medication reminders, ...), what the patient/family hope to achieve, special considerations, and required caregiver qualifications (e.g. CNA, dementia experience). Goals are durable: describe ongoing needs, never specific appointment dates, one-off events, or scheduling logistics.
            - `proposed_schedule` string: Proposed recurring care schedule (e.g., 'Mon-Fri 9am-5pm', '24/7 live-in'). Never one-off events or specific appointment dates.
          - `structured_demographics` StructuredDemographics: Structured demographics data - patient demographic information. Maps to Demographics model for structured data storage.
            - `date_of_birth` string, date: Patient's date of birth
            - `height` string: Patient height, normalized to feet-and-inches like 5'8" (accept forms like '5 foot 8' or 'five eight')
            - `weight` integer: Patient weight in pounds
            - `date_of_death` string, date: Date of death if applicable
            - `gender` 'male' | 'female': Gender choices for Demographics (separate from Person.Gender)
            - `marital_status` 'married' | 'cohabitating' | 'domestic_partnership' | 'single' | 'separated' | 'divorced' | 'widowed': Marital status choices
            - `spouse_name` string: Spouse or partner name
            - `lives_with` string: Very concise description of living arrangements. One short sentence, 10 words or fewer (e.g., 'alone', 'with daughter', 'with spouse and adult son').
            - `religion` 'christianity' | 'judaism' | 'buddhism' | 'islam' | 'hinduism' | 'other' | 'unaffiliated': Religion choices
            - `attends_services` 'unknown' | 'yes' | 'no': Religious service attendance
            - `dnr` boolean: Do Not Resuscitate status (true=Yes, false=No, null=Unknown). Set only when explicitly discussed ('has a DNR', 'no DNR', 'DNR in place').
            - `languages` Language[]: Languages spoken by patient. Default to ['english'] for a patient in the US when not discussed.
            - `past_profession` string: Previous occupation or profession
          - `structured_medical_conditions` StructuredMedicalConditions: Structured medical conditions data - patient medical conditions and functional limitations. Maps to MedicalConditions model for structured data storage.
            - `medical_conditions` string: Chronic/acute conditions, hospital stays, etc.
            - `hearing` 'good' | 'poor' | 'deaf': Hearing level choices
            - `hearing_aid` boolean: Uses hearing aid
            - `speech` 'good' | 'poor' | 'none': Speech level choices
            - `vision` 'good' | 'poor' | 'blind': Vision level choices
            - `glasses` boolean: Wears glasses
            - `swallowing` 'good' | 'poor' | 'none': Swallowing level choices
            - `other_conditions` OtherCondition[]: Other medical conditions (smoker, on oxygen, etc.)
            - `functional_limitations` FunctionalLimitation[]: Functional limitations (amputation, incontinence, etc.)
          - `structured_allergies` StructuredAllergies: Structured allergies data - known allergens and related notes. Maps to Allergies model for structured data storage.
            - `allergies` union[]: Known allergens. Prefer a value from the provided allergy list; use a free-text name only for an allergen not on the list. Use ['no_known_allergies_nka'] when the patient is explicitly stated to have no known allergies.
              - …
            - `notes` string: Additional allergy notes
          - `structured_adls` StructuredADLs: Structured ADL (Activities of Daily Living) data. Stored as sparse ADLAssessment rows keyed by dynamic ADLOption.
            - `activities` ADLValue[]: ADL task assessments. Include an entry only for tasks that are part of the care plan; omit tasks that don't apply. Each `key` must be one of the organization's configured ADL option keys.
              - …
          - `structured_iadls` StructuredIADLs: Structured IADL (Instrumental Activities of Daily Living) data. Stored as sparse IADLAssessment rows keyed by dynamic IADLOption.
            - `activities` IADLValue[]: IADL task assessments. Include an entry only for tasks that are part of the care plan; omit tasks that don't apply. Each `key` must be one of the organization's configured IADL option keys.
              - …
          - `structured_match_criteria` StructuredMatchCriteria: Structured match criteria data - caregiver matching preferences. Stored as sparse MatchCriterion rows keyed by dynamic MatchCriterionDimension.
            - `criteria` MatchCriterionValue[]: Caregiver matching preferences. Include an entry only for dimensions that are preferred or required; omit dimensions that are not needed. Include gender or language preferences only when explicitly stated. Each `key` must be one of the organization's configured match criterion dimension keys.
              - …
          - `structured_meals` StructuredMeals: Structured meals data - diet, appetite, meal scheduling, food preferences. Maps to Meals model for structured data storage.
            - `meals_assistance` MealsAssistance[]: Types of meal-related assistance needed (Cooking, Preparation, Feeding)
            - `appetite` union: Patient appetite (Poor/Good)
              - …
            - `diet` union: Diet assessment (Poor Nutrition / Desires Improved Nutrition / Special Diet)
              - …
            - `special_diet` string: Description of any special diet
            - `shopping_by` string: Who does grocery shopping
            - `breakfast_time` string, time: Scheduled breakfast time
            - `lunch_time` string, time: Scheduled lunch time
            - `dinner_time` string, time: Scheduled dinner time
            - `snacks_time` string, time: Scheduled snacks time
            - `meals_other` MealsOther[]: Other meal-related conditions (Swallowing Issues, Encourage Liquids)
            - `favorite_breakfast` string: Favorite breakfast foods
            - `favorite_lunch` string: Favorite lunch foods
            - `favorite_snack` string: Favorite snack foods
            - `favorite_dinner` string: Favorite dinner foods
            - `notes` string: Additional meals-related notes
          - `structured_driving` StructuredDriving: Structured driving data - vehicle arrangement, errands, doctor appointments, notes. Maps to Driving model for structured data storage.
            - `vehicle` Vehicle[]: Vehicle / transportation arrangement (Client Drives, Needs Caregiver)
            - `caregiver_vehicle` union: Whose car the caregiver drives (Aide's Car / Client's Car)
              - …
            - `errands_description` string: Errands the caregiver helps with
            - `doctor_appointment_description` string: Ongoing doctor's-appointment transport needs (e.g. 'monthly cardiology', 'weekly PT'); never specific appointment dates or times
            - `notes` string: Additional driving notes
          - `structured_transfers` StructuredTransfers: Structured transfers data - transfer types, aids used, risks, notes. Maps to Transfers model for structured data storage.
            - `transfer_types` string: How the patient transfers (e.g. stand pivot, two-person assist)
            - `transfer_aides` TransferAide[]: Aids used to help the patient transfer (Gait Belt, Hoyer, Other)
            - `aides_other` string: Description of any other transfer aid (when Other is selected)
            - `transfer_risks` string: Risks associated with transferring the patient
            - `notes` string: Additional transfer notes
          - `structured_equipment` StructuredEquipmentEnvironment: Structured equipment / environment data - in-home equipment, safety, and accessibility. Maps to EquipmentEnvironment model for structured data storage.
            - `safety_assessment_done` boolean: Whether a home safety assessment has been completed
            - `interested_in_lifeline` boolean: Whether the patient is interested in a Lifeline / medical alert system
            - `equipment` EquipmentItem[]: In-home equipment and environment modifications. Use 'other' for an item not on the list and describe it in `equipment_other`.
            - `equipment_other` string: Description of any other equipment or environment modification (when 'other' is selected)
            - `notes` string: Additional equipment / environment notes
          - `care_plan_id` integer: The ID of the care plan to update
          - `post_hoc_action_id` integer: Post hoc action ID - marks the action as complete after care plan creation
  - `has_transcript` boolean, required

## Other responses

- `401`: Unauthorized
- `403`: Forbidden
- `404`: Not Found
- `422`: Unprocessable Content

---

[API](https://skmtc.dev/sagecare/apis/sage-api-v1.md) - [All operations](https://skmtc.dev/sagecare/apis/sage-api-v1/llms.txt) - [OpenAPI document](https://skmtc.dev/sagecare/apis/sage-api-v1/revisions/36b26ceace69?raw)