API Evangelist conversational phrasing for Junction Order API

# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for Junction Order API
  version: 1.0.0
extends: openapi/vital-io-order-api-openapi.yml
actions:
- target: $.info
  update:
    x-apievangelist-phrasing:
      method: generated
      generated: '2026-10-01'
      generator: build-phrasing.py
      label: Generated by API Evangelist
      operations: 33
- target: $.paths['/v3/order/testkit/register'].post
  update:
    x-apievangelist-phrasing:
      intent: Register a received test kit
      effect: write
      questions:
      - How does a patient register a test kit they received?
      - Can I register a kit by its sample ID together with patient details?
      instructions:
      - text: Register test kit {sample_id} for patient {patient_details} at {patient_address}.
        slots:
          sample_id: requestBody.sample_id
          patient_details: requestBody.patient_details
          patient_address: requestBody.patient_address
      - text: Register sample {sample_id} to user {user} with details {patient_details} and address {patient_address}.
        slots:
          sample_id: requestBody.sample_id
          user: requestBody.user_id
          patient_details: requestBody.patient_details
          patient_address: requestBody.patient_address
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v3/order/testkit'].post
  update:
    x-apievangelist-phrasing:
      intent: Order an unregistered test kit
      effect: write
      questions:
      - Can I ship an at-home test kit to a user before it's registered?
      - What do I need to order a test kit for a lab test?
      instructions:
      - text: Order a test kit for lab test {lab_test} for user {user}, shipping to {shipping}.
        slots:
          lab_test: requestBody.lab_test_id
          user: requestBody.user_id
          shipping: requestBody.shipping_details
      - text: Ship a {lab_test} kit to {user} at {shipping}.
        slots:
          lab_test: requestBody.lab_test_id
          user: requestBody.user_id
          shipping: requestBody.shipping_details
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v3/order/phlebotomy/appointment/availability'].post
  update:
    x-apievangelist-phrasing:
      intent: Find at-home blood draw time slots
      effect: read
      questions:
      - What at-home blood draw time slots are open near a patient's address?
      - Can I check mobile phlebotomist availability starting from a specific date?
      instructions:
      - text: Find at-home phlebotomy slots at {first_line}, {city}, {state} {zip}.
        slots:
          first_line: requestBody.first_line
          city: requestBody.city
          state: requestBody.state
          zip: requestBody.zip_code
      - text: Check mobile phlebotomist availability for {first_line}, {zip} from {start_date}.
        slots:
          first_line: requestBody.first_line
          zip: requestBody.zip_code
          start_date: query.start_date
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v3/order/{order_id}/phlebotomy/appointment/book'].post
  update:
    x-apievangelist-phrasing:
      intent: Book an at-home blood draw
      effect: write
      questions:
      - How do I book an at-home blood draw for an order?
      - Can I leave notes for the phlebotomist when booking a home visit?
      instructions:
      - text: Book at-home phlebotomy for order {order_id} using slot {booking_key}.
        slots:
          order_id: path.order_id
          booking_key: requestBody.booking_key
      - text: Book home draw slot {booking_key} for order {order_id} with notes {notes}.
        slots:
          booking_key: requestBody.booking_key
          order_id: path.order_id
          notes: requestBody.appointment_notes
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v3/order/{order_id}/phlebotomy/appointment/request'].post
  update:
    x-apievangelist-phrasing:
      intent: Request an at-home blood draw
      effect: write
      questions:
      - Can I request an at-home draw without picking a specific time slot?
      - Is there a way to request a home phlebotomy visit through a particular provider?
      instructions:
      - text: Request an at-home phlebotomy appointment for order {order_id} at {address} via {provider}.
        slots:
          order_id: path.order_id
          address: requestBody.address
          provider: requestBody.provider
      - text: Ask {provider} to schedule a home draw for order {order_id} at {address}.
        slots:
          provider: requestBody.provider
          order_id: path.order_id
          address: requestBody.address
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v3/order/{order_id}/phlebotomy/appointment/reschedule'].patch
  update:
    x-apievangelist-phrasing:
      intent: Reschedule an at-home blood draw
      effect: write
      questions:
      - Can I move a booked at-home blood draw to another time?
      - What do I need to change the slot of a home phlebotomy visit?
      instructions:
      - text: Reschedule order {order_id}'s home draw to slot {booking_key}.
        slots:
          order_id: path.order_id
          booking_key: requestBody.booking_key
      - text: Move the at-home phlebotomy visit for {order_id} to {booking_key}.
        slots:
          order_id: path.order_id
          booking_key: requestBody.booking_key
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v3/order/{order_id}/phlebotomy/appointment/cancel'].patch
  update:
    x-apievangelist-phrasing:
      intent: Cancel an at-home blood draw
      effect: destructive
      questions:
      - How do I cancel an at-home phlebotomy appointment?
      - Do I need a cancellation reason to call off a home blood draw?
      instructions:
      - text: Cancel the at-home draw for order {order_id} with reason {reason}.
        slots:
          order_id: path.order_id
          reason: requestBody.cancellation_reason_id
      - text: Call off order {order_id}'s home phlebotomy visit, reason {reason}, notes {cancel_notes}.
        slots:
          order_id: path.order_id
          reason: requestBody.cancellation_reason_id
          cancel_notes: requestBody.notes
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v3/order/phlebotomy/appointment/cancellation-reasons'].get
  update:
    x-apievangelist-phrasing:
      intent: List reasons for cancelling a home draw
      effect: read
      questions:
      - What reasons are accepted for cancelling an at-home blood draw?
      - Where do I get the reason IDs for home phlebotomy cancellations?
      instructions:
      - text: List cancellation reasons for at-home phlebotomy.
      - text: Show the reason codes for cancelling a home draw.
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v3/order/{order_id}/phlebotomy/appointment'].get
  update:
    x-apievangelist-phrasing:
      intent: Get an order's at-home draw appointment
      effect: read
      questions:
      - When is the at-home blood draw scheduled for an order?
      - Can I see the status of an order's home phlebotomy visit?
      instructions:
      - text: Get the at-home phlebotomy appointment for order {order_id}.
        slots:
          order_id: path.order_id
      - text: Show order {order_id}'s home draw booking.
        slots:
          order_id: path.order_id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v3/order/area/info'].get
  update:
    x-apievangelist-phrasing:
      intent: Check lab-testing coverage for a zip code
      effect: read
      questions:
      - Is a zip code covered by the at-home phlebotomy network?
      - Which lab locations serve patients within a radius of a zip code?
      instructions:
      - text: Check lab-testing coverage for zip {zip_code}.
        slots:
          zip_code: query.zip_code
      - text: Get area info for {zip_code} within radius {radius} for lab {lab}.
        slots:
          zip_code: query.zip_code
          radius: query.radius
          lab: query.lab
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v3/order/psc/info'].get
  update:
    x-apievangelist-phrasing:
      intent: Find a lab's patient service centers near a zip
      effect: read
      questions:
      - Where are a lab's nearest patient service centers for a zip code?
      - Can I filter service centers by their capabilities?
      instructions:
      - text: Find patient service centers for lab {lab_id} near {zip_code}.
        slots:
          lab_id: query.lab_id
          zip_code: query.zip_code
      - text: List {lab_id} service centers within {radius} of {zip_code} with capabilities {capabilities}.
        slots:
          lab_id: query.lab_id
          radius: query.radius
          zip_code: query.zip_code
          capabilities: query.capabilities
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v3/order/{order_id}/psc/info'].get
  update:
    x-apievangelist-phrasing:
      intent: Find service centers for an existing order
      effect: read
      questions:
      - Which patient service centers can a patient visit for an order already placed?
      - Can I widen the search radius for an order's service centers?
      instructions:
      - text: Find patient service centers for order {order_id}.
        slots:
          order_id: path.order_id
      - text: List service centers within {radius} for order {order_id}.
        slots:
          radius: query.radius
          order_id: path.order_id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v3/order/{order_id}/result/pdf'].get
  update:
    x-apievangelist-phrasing:
      intent: Download an order's results PDF
      effect: read
      questions:
      - Can I download the lab results PDF for an order?
      - Where's the printable results report for an order?
      instructions:
      - text: Download the results PDF for order {order_id}.
        slots:
          order_id: path.order_id
      - text: Get order {order_id}'s lab result report as a PDF.
        slots:
          order_id: path.order_id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v3/order/{order_id}/result/metadata'].get
  update:
    x-apievangelist-phrasing:
      intent: Get an order's result metadata
      effect: read
      questions:
      - What lab, provider and sample dates are attached to an order's results?
      - Can I get result metadata without the test values?
      instructions:
      - text: Get result metadata for order {order_id}.
        slots:
          order_id: path.order_id
      - text: Show the lab and sample dates on order {order_id}'s results.
        slots:
          order_id: path.order_id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v3/order/{order_id}/result'].get
  update:
    x-apievangelist-phrasing:
      intent: Get an order's raw result data
      effect: read
      questions:
      - Can I get an order's lab results as raw JSON data?
      - Is there a machine-readable version of results with metadata included?
      instructions:
      - text: Get raw JSON results for order {order_id}.
        slots:
          order_id: path.order_id
      - text: Pull order {order_id}'s test data and metadata as JSON.
        slots:
          order_id: path.order_id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v3/order/{order_id}/labels/pdf'].get
  update:
    x-apievangelist-phrasing:
      intent: Print specimen labels for an order
      effect: read
      questions:
      - How do I print specimen labels for an order?
      - Can I choose how many labels to print and set the collection date?
      instructions:
      - text: Print labels for order {order_id} collected on {collection_date}.
        slots:
          order_id: path.order_id
          collection_date: query.collection_date
      - text: Get {number} labels for order {order_id} with collection date {collection_date}.
        slots:
          number: query.number_of_labels
          order_id: path.order_id
          collection_date: query.collection_date
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v3/order/psc/appointment/availability'].post
  update:
    x-apievangelist-phrasing:
      intent: Find service center appointment slots
      effect: read
      questions:
      - What appointment times are open at a lab's patient service centers?
      - Can I check service center availability by site code or zip code?
      instructions:
      - text: Find service center appointment slots for lab {lab} near {zip_code}.
        slots:
          lab: query.lab
          zip_code: query.zip_code
      - text: Check availability at sites {site_codes} for {lab} from {start_date}.
        slots:
          site_codes: query.site_codes
          lab: query.lab
          start_date: query.start_date
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v3/order/{order_id}/psc/appointment/book'].post
  update:
    x-apievangelist-phrasing:
      intent: Book a patient service center visit
      effect: write
      questions:
      - How do I book a patient service center visit for an order?
      - Can I use an idempotency key when booking a service center appointment?
      instructions:
      - text: Book service center slot {booking_key} for order {order_id}.
        slots:
          booking_key: requestBody.booking_key
          order_id: path.order_id
      - text: Reserve a patient service center appointment for {order_id} using {booking_key}.
        slots:
          order_id: path.order_id
          booking_key: requestBody.booking_key
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v3/order/{order_id}/psc/appointment/reschedule'].patch
  update:
    x-apievangelist-phrasing:
      intent: Reschedule a patient service center visit
      effect: write
      questions:
      - Can I move a patient service center appointment to a different slot?
      - What's needed to rebook a lab site visit for an order?
      instructions:
      - text: Reschedule order {order_id}'s service center visit to slot {booking_key}.
        slots:
          order_id: path.order_id
          booking_key: requestBody.booking_key
      - text: Rebook the patient service center appointment on {order_id} to {booking_key}.
        slots:
          order_id: path.order_id
          booking_key: requestBody.booking_key
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v3/order/{order_id}/psc/appointment/cancel'].patch
  update:
    x-apievangelist-phrasing:
      intent: Cancel a patient service center visit
      effect: destructive
      questions:
      - How do I cancel a patient service center appointment?
      - Can I leave a note when cancelling a lab site visit?
      instructions:
      - text: Cancel the service center appointment for order {order_id} with reason {psc_reason}.
        slots:
          order_id: path.order_id
          psc_reason: requestBody.cancellationReasonId
      - text: Cancel {order_id}'s lab site visit, reason {psc_reason}, note {note}.
        slots:
          order_id: path.order_id
          psc_reason: requestBody.cancellationReasonId
          note: requestBody.note
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v3/order/psc/appointment/cancellation-reasons'].get
  update:
    x-apievangelist-phrasing:
      intent: List reasons for cancelling a service center visit
      effect: read
      questions:
      - What reasons can I give for cancelling a service center appointment?
      - Where do I find reason IDs for patient service center cancellations?
      instructions:
      - text: List cancellation reasons for service center appointments.
      - text: Show the reason codes for cancelling a lab site visit.
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v3/order/{order_id}/psc/appointment'].get
  update:
    x-apievangelist-phrasing:
      intent: Get an order's service center appointment
      effect: read
      questions:
      - When is the patient service center appointment for an order?
      - Can I check the booking details of an order's lab site visit?
      instructions:
      - text: Get the service center appointment for order {order_id}.
        slots:
          order_id: path.order_id
      - text: Show order {order_id}'s patient service center booking.
        slots:
          order_id: path.order_id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v3/order/resend_events'].post
  update:
    x-apievangelist-phrasing:
      intent: Replay order webhooks
      effect: write
      questions:
      - Can I replay order webhooks I missed?
      - Is it possible to resend order events for a time window?
      instructions:
      - text: Resend webhooks for orders {order_ids}.
        slots:
          order_ids: requestBody.order_ids
      - text: Replay order events from {start_at} to {end_at}.
        slots:
          start_at: requestBody.start_at
          end_at: requestBody.end_at
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v3/order/{order_id}/collection_instruction_pdf'].get
  update:
    x-apievangelist-phrasing:
      intent: Get an order's collection instructions
      effect: read
      questions:
      - Where can I get the collection instructions for a specific order?
      - Does an order come with a sample collection guide PDF?
      instructions:
      - text: Get the collection instructions PDF for order {order_id}.
        slots:
          order_id: path.order_id
      - text: Download order {order_id}'s collection guide.
        slots:
          order_id: path.order_id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v3/order/{order_id}/requisition/pdf'].get
  update:
    x-apievangelist-phrasing:
      intent: Get an order's requisition form
      effect: read
      questions:
      - How do I get the requisition form for an order?
      - Can I download an order's requisition as a PDF?
      instructions:
      - text: Get the requisition PDF for order {order_id}.
        slots:
          order_id: path.order_id
      - text: Download order {order_id}'s lab requisition form.
        slots:
          order_id: path.order_id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v3/order/{order_id}/abn_pdf'].get
  update:
    x-apievangelist-phrasing:
      intent: Get an order's ABN form
      effect: read
      questions:
      - Where do I get the Advance Beneficiary Notice for an order?
      - Is there an ABN PDF for an order?
      instructions:
      - text: Get the ABN PDF for order {order_id}.
        slots:
          order_id: path.order_id
      - text: Download the Advance Beneficiary Notice for {order_id}.
        slots:
          order_id: path.order_id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v3/order/{order_id}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a lab order
      effect: read
      questions:
      - What's the current status of a lab order?
      - Can I look up one order by its ID?
      instructions:
      - text: Get order {order_id}.
        slots:
          order_id: path.order_id
      - text: Show me the details of lab order {order_id}.
        slots:
          order_id: path.order_id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v3/order/{order_id}'].patch
  update:
    x-apievangelist-phrasing:
      intent: Change an order's activation date
      effect: write
      questions:
      - Can I change when an order is scheduled to activate?
      - Which order statuses still allow changing the activation date?
      instructions:
      - text: Set order {order_id} to activate on {activate_by}.
        slots:
          order_id: path.order_id
          activate_by: requestBody.activate_by
      - text: Push back the activation date of {order_id} to {activate_by}.
        slots:
          order_id: path.order_id
          activate_by: requestBody.activate_by
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v3/order'].post
  update:
    x-apievangelist-phrasing:
      intent: Place a lab order for a patient
      effect: write
      questions:
      - How do I place a lab order for a patient?
      - Can I attach ICD codes and health insurance when creating an order?
      instructions:
      - text: Create an order for user {user} for lab test {lab_test} with patient {patient_details} at {patient_address}.
        slots:
          user: requestBody.user_id
          lab_test: requestBody.lab_test_id
          patient_details: requestBody.patient_details
          patient_address: requestBody.patient_address
      - text: Place a {priority} priority order for {user} with ICD codes {icd_codes}.
        slots:
          priority: requestBody.priority
          user: requestBody.user_id
          icd_codes: requestBody.icd_codes
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v3/order/import'].post
  update:
    x-apievangelist-phrasing:
      intent: Import an order for an existing sample
      effect: write
      questions:
      - Can I import an order for a sample that was already collected?
      - What's required to bring an existing sample in as an order?
      instructions:
      - text: Import an order for sample {sample_id} for user {user}.
        slots:
          sample_id: requestBody.sample_id
          user: requestBody.user_id
      - text: Import sample {sample_id} for {user} with order set {order_set}, billed as {billing_type}.
        slots:
          sample_id: requestBody.sample_id
          user: requestBody.user_id
          order_set: requestBody.order_set
          billing_type: requestBody.billing_type
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v3/order/{order_id}/cancel'].post
  update:
    x-apievangelist-phrasing:
      intent: Cancel a lab order
      effect: destructive
      questions:
      - How do I cancel a lab order?
      - Can an order be cancelled after it's placed?
      instructions:
      - text: Cancel order {order_id}.
        slots:
          order_id: path.order_id
      - text: Cancel lab order {order_id} now.
        slots:
          order_id: path.order_id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v3/order/{order_id}/test'].post
  update:
    x-apievangelist-phrasing:
      intent: Simulate an order's status progression
      effect: write
      questions:
      - Can I simulate an order moving through its statuses for testing?
      - Can I set the final status and delay when simulating an order?
      instructions:
      - text: Simulate order {order_id} through to status {final_status}.
        slots:
          order_id: path.order_id
          final_status: query.final_status
      - text: Simulate processing for {order_id} with a {delay} delay.
        slots:
          order_id: path.order_id
          delay: query.delay
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v3/order/{order_id}/draw_completed'].patch
  update:
    x-apievangelist-phrasing:
      intent: Mark an on-site draw as completed
      effect: write
      questions:
      - How do I mark an on-site collection order's draw as completed?
      - What updates an on-site order once the blood draw is done?
      instructions:
      - text: Mark the draw completed for order {order_id}.
        slots:
          order_id: path.order_id
      - text: Record that on-site collection for {order_id} is done.
        slots:
          order_id: path.order_id
      method: generated
      generated: '2026-10-01'