# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for Elation Health Patients API
  version: 1.0.0
extends: openapi/elation-health-patients-api-openapi.yml
actions:
- target: $.info
  update:
    x-apievangelist-phrasing:
      method: generated
      generated: '2026-10-02'
      generator: build-phrasing.py
      label: Generated by API Evangelist
      operations: 24
- target: $.paths['/patients/:id/'].put
  update:
    x-apievangelist-phrasing:
      intent: Update a patient via the colon-style legacy path
      effect: write
      questions:
      - Is there an older Elation endpoint written as /patients/:id/ for editing a patient?
      - What does the colon-placeholder patient update route accept?
      instructions:
      - text: Send a patient update through the legacy /patients/:id/ colon path.
      - text: Use the colon-style patient update route to push my edited chart demographics.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/patients/{id}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a patient from the no-trailing-slash path
      effect: read
      questions:
      - Can I fetch a patient from a patients URL that has no trailing slash?
      - Which legacy lookup returns a patient chart when the URL has no ending slash?
      instructions:
      - text: Get patient {id} from the /patients/{id} path that has no trailing slash.
        slots:
          id: path.id
      - text: Look up chart {id} using the slashless legacy patient route.
        slots:
          id: path.id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/patients/{id}/'].get
  update:
    x-apievangelist-phrasing:
      intent: Retrieve a patient's details by ID
      effect: read
      questions:
      - How do I pull the details for one specific patient by their ID from the legacy endpoint?
      - What demographic details come back when I retrieve a single patient on the unversioned path?
      instructions:
      - text: Retrieve the details for patient {id} from the unversioned /patients/{id}/ endpoint.
        slots:
          id: path.id
      - text: Show me everything on file for patient ID {id}.
        slots:
          id: path.id
      method: generated
      generated: '2026-10-02'
- target: $.paths['/patients/{id}/'].put
  update:
    x-apievangelist-phrasing:
      intent: Replace all fields on a patient record
      effect: write
      questions:
      - Can I overwrite every field on a patient record at once, including pronouns and preferred language?
      - Which fields are mandatory when replacing a whole patient on the unversioned path?
      instructions:
      - text: Replace patient {id} with first name {first_name}, last name {last_name}, DOB {dob} and sex {sex}.
        slots:
          id: path.id
          first_name: requestBody.first_name
          last_name: requestBody.last_name
          dob: requestBody.dob
          sex: requestBody.sex
      - text: Overwrite patient {id} in full, setting primary physician {primary_physician} and practice {caregiver_practice}.
        slots:
          id: path.id
          primary_physician: requestBody.primary_physician
          caregiver_practice: requestBody.caregiver_practice
      method: generated
      generated: '2026-09-26'
- target: $.paths['/patients/{id}/'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete a patient via the legacy endpoint
      effect: destructive
      questions:
      - How do I remove a patient chart using the older unversioned delete route?
      - Which older unversioned endpoint deletes a single patient by ID?
      instructions:
      - text: Delete patient {id} through the legacy /patients/{id}/ route.
        slots:
          id: path.id
      - text: Remove the chart for patient {id} using the unversioned delete call.
        slots:
          id: path.id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/patients/{id}/'].patch
  update:
    x-apievangelist-phrasing:
      intent: Patch a patient via the legacy endpoint
      effect: write
      questions:
      - Can I patch just part of a patient on the older unversioned PATCH route?
      - Is there a legacy PATCH call for editing one patient without the v2.0 prefix?
      instructions:
      - text: Patch patient {id} with only the fields I changed, using the legacy PATCH route.
        slots:
          id: path.id
      - text: Send a partial legacy edit to chart {id} without resending the full record.
        slots:
          id: path.id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/patients/'].get
  update:
    x-apievangelist-phrasing:
      intent: Search patients across a practice
      effect: read
      questions:
      - How can I find patients by name and date of birth on the legacy patient search?
      - Can I search patients by insurance member ID or group ID using the older find endpoint?
      - Which patients were modified after a given date, per the legacy find call?
      instructions:
      - text: Find patients named {first_name} {last_name} born {dob} with the legacy patient search.
        slots:
          first_name: query.first_name
          last_name: query.last_name
          dob: query.dob
      - text: Search the older patient finder for members with insurance member ID {member_id}.
        slots:
          member_id: query.member_id
      - text: Find patients in practice {practice} modified since {last_modified__gte} on the legacy finder.
        slots:
          practice: query.practice
          last_modified__gte: query.last_modified__gte
      method: generated
      generated: '2026-09-26'
- target: $.paths['/patients/'].post
  update:
    x-apievangelist-phrasing:
      intent: Register a new patient via the legacy endpoint
      effect: write
      questions:
      - What is the minimum I need to register a patient through the older unversioned create call?
      - Can I attach insurance when I add a new patient on the legacy route?
      instructions:
      - text: Register a new patient {first_name} {last_name}, born {dob}, sex {sex}, on the legacy create route.
        slots:
          first_name: requestBody.first_name
          last_name: requestBody.last_name
          dob: requestBody.dob
          sex: requestBody.sex
      - text: Add a legacy patient record under physician {primary_physician} at practice {caregiver_practice}.
        slots:
          primary_physician: requestBody.primary_physician
          caregiver_practice: requestBody.caregiver_practice
      method: generated
      generated: '2026-09-26'
- target: $.paths['/patients/{id}/insurance_cards/'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a patient's insurance card images
      effect: read
      questions:
      - How do I see the scanned insurance cards on a patient's chart?
      - Can I get both the front and back images of a patient's insurance card?
      instructions:
      - text: Get the insurance card images for patient {id}.
        slots:
          id: path.id
      - text: Show me the scanned insurance cards on file for chart {id}.
        slots:
          id: path.id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/patients/{id}/insurance_cards/'].post
  update:
    x-apievangelist-phrasing:
      intent: Upload an insurance card image for a patient
      effect: write
      questions:
      - How do I upload a photo of a patient's insurance card?
      - Can I upload the back side of a secondary insurance card separately?
      instructions:
      - text: Upload insurance card image {image} for patient {id} as side {side} of rank {rank}.
        slots:
          image: requestBody.image
          id: path.id
          side: requestBody.side
          rank: requestBody.rank
      - text: Attach a card scan to patient {id}'s primary insurance, front side {side}.
        slots:
          id: path.id
          side: requestBody.side
      method: generated
      generated: '2026-09-26'
- target: $.paths['/patients/{id}/insurance_cards/'].delete
  update:
    x-apievangelist-phrasing:
      intent: Remove a patient's insurance card image
      effect: destructive
      questions:
      - How do I delete an outdated insurance card scan from a patient's chart?
      - Can I archive an insurance card image instead of deleting it outright?
      instructions:
      - text: Delete the {side} side of the rank {rank} insurance card for patient {id}.
        slots:
          side: query.side
          rank: query.rank
          id: path.id
      - text: Archive patient {id}'s insurance card image for rank {rank}, side {side}, with archive set to {archive}.
        slots:
          id: path.id
          rank: query.rank
          side: query.side
          archive: query.archive
      method: generated
      generated: '2026-09-26'
- target: $.paths['/patients/{patient_id}/profile_image'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a patient's profile photo (legacy)
      effect: read
      questions:
      - How do I fetch a patient's headshot from the older profile_image route?
      - Does the legacy patient photo endpoint return the image for a patient_id?
      instructions:
      - text: Get the profile photo for patient {patient_id} from the legacy profile_image route.
        slots:
          patient_id: path.patient_id
      - text: Download patient {patient_id}'s headshot using the older photo lookup.
        slots:
          patient_id: path.patient_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/patients/{patient_id}/profile_image'].post
  update:
    x-apievangelist-phrasing:
      intent: Upload a patient profile photo (legacy)
      effect: write
      questions:
      - How do I set a patient's headshot by sending a base64 image on the older route?
      - What does the legacy photo upload need besides the image data?
      instructions:
      - text: Upload base64 image {base_64} named {original_filename} as patient {patient_id}'s headshot via the legacy route.
        slots:
          base_64: requestBody.base_64
          original_filename: requestBody.original_filename
          patient_id: path.patient_id
      - text: Set the legacy profile picture for patient {patient_id} in practice {practice}.
        slots:
          patient_id: path.patient_id
          practice: requestBody.practice
      method: generated
      generated: '2026-09-26'
- target: $.paths['/patients/{patient_id}/profile_image/'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete a patient's profile photo (legacy)
      effect: destructive
      questions:
      - How do I clear a patient's headshot using the older profile_image delete?
      - Can I remove a wrong profile picture from a chart on the legacy route?
      instructions:
      - text: Delete the legacy profile photo for patient {patient_id}.
        slots:
          patient_id: path.patient_id
      - text: Clear patient {patient_id}'s headshot through the older delete route.
        slots:
          patient_id: path.patient_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/patients/{id}/incoming_files'].post
  update:
    x-apievangelist-phrasing:
      intent: File incoming documents to a patient chart
      effect: write
      questions:
      - How do I file faxed or uploaded documents into a patient's chart?
      - Can I mark a filed document urgent and assign a reviewer?
      - Which document type and tags can I set when filing incoming files?
      instructions:
      - text: File incoming files {files} to patient {id}'s chart as document type {document_type}.
        slots:
          files: requestBody.files
          id: path.id
          document_type: requestBody.document_type
      - text: File documents {files} into chart {id} titled {custom_title} and route them to reviewer {reviewer_user}.
        slots:
          files: requestBody.files
          id: path.id
          custom_title: requestBody.custom_title
          reviewer_user: requestBody.reviewer_user
      method: generated
      generated: '2026-09-26'
- target: $.paths['/patients/{patient_id}/patient_provider_team'].get
  update:
    x-apievangelist-phrasing:
      intent: List a patient's care team members
      effect: read
      questions:
      - Who is on a patient's provider care team?
      - How can I see which clinicians are assigned to a patient's team?
      instructions:
      - text: List the care team members for patient {patient_id}.
        slots:
          patient_id: path.patient_id
      - text: Show me who belongs to patient {patient_id}'s provider team.
        slots:
          patient_id: path.patient_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/patients/{patient_id}/patient_provider_team'].post
  update:
    x-apievangelist-phrasing:
      intent: Create a provider team for a patient
      effect: write
      questions:
      - Can I set up a care team for a patient who doesn't have one yet?
      - How do I assemble a new provider team around a patient?
      instructions:
      - text: Create a provider team for patient {patient_id}.
        slots:
          patient_id: path.patient_id
      - text: Set up a new care team record around patient {patient_id}.
        slots:
          patient_id: path.patient_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/patients/{id}/outstanding_balance/'].post
  update:
    x-apievangelist-phrasing:
      intent: Update a patient's outstanding balance
      effect: write
      questions:
      - How do I record what a patient still owes the practice?
      - Can I push an updated outstanding balance from my billing system to a patient?
      instructions:
      - text: Set patient {id}'s outstanding balance to {balance}.
        slots:
          id: path.id
          balance: requestBody.balance
      - text: Update the amount owed on chart {id} to {balance}.
        slots:
          id: path.id
          balance: requestBody.balance
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/2.0/patients/'].get
  update:
    x-apievangelist-phrasing:
      intent: List patients with filters and paging
      effect: read
      questions:
      - How do I page through all patients with limit and offset in the v2.0 API?
      - Can I look up a patient by phone number?
      - Which patients match a given insurance plan, sorted my way?
      instructions:
      - text: List v2.0 patients with phone number {phone_number}.
        slots:
          phone_number: query.phone_number
      - text: Page through patients {limit} at a time starting at offset {offset}, ordered by {order_by}.
        slots:
          limit: query.limit
          offset: query.offset
          order_by: query.order_by
      - text: List patients on insurance plan {insurance_plan} changed before {last_modified__lt}.
        slots:
          insurance_plan: query.insurance_plan
          last_modified__lt: query.last_modified__lt
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/2.0/patients/'].post
  update:
    x-apievangelist-phrasing:
      intent: Create a patient with full demographics
      effect: write
      questions:
      - Can I create a patient in the v2.0 API with emergency contact, employer and guarantor?
      - What fields does the v2.0 create-patient call require?
      instructions:
      - text: Create v2.0 patient {first_name} {last_name}, DOB {dob}, sex {sex}, with emergency contact {emergency_contact}.
        slots:
          first_name: requestBody.first_name
          last_name: requestBody.last_name
          dob: requestBody.dob
          sex: requestBody.sex
          emergency_contact: requestBody.emergency_contact
      - text: Enroll a new patient with physician {primary_physician}, practice {caregiver_practice} and timezone {timezone}.
        slots:
          primary_physician: requestBody.primary_physician
          caregiver_practice: requestBody.caregiver_practice
          timezone: requestBody.timezone
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/2.0/patients/{id}/'].get
  update:
    x-apievangelist-phrasing:
      intent: Retrieve a patient from the v2.0 API
      effect: read
      questions:
      - How do I get a single patient record from the v2.0 API?
      - Does the v2.0 patient lookup include consents and guarantor details?
      instructions:
      - text: Fetch v2.0 patient {id}.
        slots:
          id: path.id
      - text: Pull the /api/2.0 record for patient {id}, including consents and preferences.
        slots:
          id: path.id
      method: generated
      generated: '2026-10-02'
- target: $.paths['/api/2.0/patients/{id}/'].put
  update:
    x-apievangelist-phrasing:
      intent: Replace a patient record in the v2.0 API
      effect: write
      questions:
      - How do I fully replace a patient in the v2.0 API, including previous names and address?
      - What must I resend when doing a full v2.0 patient replace?
      instructions:
      - text: Replace v2.0 patient {id} with previous last name {previous_last_name} and occupation {occupation}.
        slots:
          id: path.id
          previous_last_name: requestBody.previous_last_name
          occupation: requestBody.occupation
      - text: Do a full /api/2.0 replace of patient {id} keeping DOB {dob} and SMS opt-in {sms_opt_in_status}.
        slots:
          id: path.id
          dob: requestBody.dob
          sms_opt_in_status: requestBody.sms_opt_in_status
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/2.0/patients/{id}/'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete a patient in the v2.0 API
      effect: destructive
      questions:
      - How do I delete a patient using the /api/2.0 endpoint?
      - What happens to a chart when I call the v2.0 patient delete?
      instructions:
      - text: Delete v2.0 patient {id}.
        slots:
          id: path.id
      - text: Remove patient {id} via the /api/2.0 delete call.
        slots:
          id: path.id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/2.0/patients/{id}/'].patch
  update:
    x-apievangelist-phrasing:
      intent: Partially update a patient in the v2.0 API
      effect: write
      questions:
      - Can I change only a patient's preferred language or pronouns in the v2.0 API?
      - How do I mark a patient VIP without resending the whole v2.0 record?
      instructions:
      - text: Set preferred language {preferred_language} on v2.0 patient {id}.
        slots:
          preferred_language: requestBody.preferred_language
          id: path.id
      - text: Flag patient {id} as VIP {vip} and set patient status {patient_status}.
        slots:
          id: path.id
          vip: requestBody.vip
          patient_status: requestBody.patient_status
      method: generated
      generated: '2026-09-26'