openapi: 3.1.0
info:
  title: NovaMed Partner API
  version: 1.0.0
  description: >
    The NovaMed Partner API enables healthcare partners to integrate with
    NovaMed for patient care management, prescription fulfillment, and order
    tracking.


    **Authentication:** All requests require an `x-api-key` header with your API
    key.


    **Base URLs:**

    - Development: `https://novamed-feapidev.nimbushealthcaretest.com`

    - Production: `https://feapi.novamed.care`


    For detailed guides, see the [Getting Started](/guides/quickstart)
    documentation.
  contact:
    name: NovaMed API Support
    email: api@nimbus-os.com
  license:
    name: API License Terms & Conditions
    url: https://developer.nimbus-os.com/api-terms
servers:
  - url: https://novamed-feapidev.nimbushealthcaretest.com
    description: Development environment
  - url: https://feapi.novamed.care
    description: Production environment
security:
  - ApiKeyAuth: []
tags:
  - name: Practitioners
    description: Manage practitioners (doctors, veterinarians) in the system
  - name: Patients
    description: Patient registration and management
  - name: Medication Requests
    description: Medication order management
  - name: Refills
    description: Prescription refill request management
  - name: Carriers
    description: Retrieve available shipment carriers
  - name: Webhooks
    description: Webhook configuration for receiving event notifications
paths:
  /api/external/practitioner:
    post:
      tags:
        - Practitioners
      summary: Create Practitioner
      description: >
        Creates a new practitioner (doctor or veterinarian) in the system. This
        endpoint is used to onboard practitioners by collecting their personal,
        professional, and contact information.


        **Notes:**

        - All required fields must be provided and valid

        - `assigned_clinic` must reference an existing clinic UUID

        - Validation errors will return descriptive messages for each field
      operationId: createPractitioner
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PractitionerRequest'
            examples:
              basic:
                summary: Create a new practitioner
                value:
                  first_name: John
                  last_name: Doe
                  email: john.doe@example.com
                  npi: '1234567890'
                  is_veterinarian: true
                  assigned_clinic: 550e8400-e29b-41d4-a716-446655440001
                  phone: '1234567890'
                  address_line_1: 123 Main St
                  address_line_2: Apt 1
                  city: San Antonio
                  state_code: TX
                  zip_code: '78201'
      responses:
        '200':
          description: Practitioner created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PractitionerResponse'
              examples:
                success:
                  summary: Successful creation
                  value:
                    success: true
                    data:
                      practitioner_id: 660e8400-e29b-41d4-a716-446655440001
                    message: Practitioner created successfully
        '400':
          description: Bad request (validation error)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized (missing or invalid API key)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                success: false
                error:
                  message: Unauthorized
  /api/external/patient:
    post:
      tags:
        - Patients
      summary: Create Patient
      description: |
        Register a new patient in NovaMed under your partner account.

        **Notes:**
        - All required fields must be provided
        - `clinic_id` must reference an existing clinic UUID
        - Address information is required for shipping
      operationId: createPatient
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PatientRequest'
            examples:
              basic:
                summary: Create a new patient
                value:
                  first_name: John
                  middle_name: Michael
                  last_name: Doe
                  gender: male
                  dob: '1985-03-15'
                  species: human
                  status: active
                  practitioner_id: 550e8400-e29b-41d4-a716-446655440001
                  assigned_clinic: 550e8400-e29b-41d4-a716-446655440002
                  contacts:
                    - key: email
                      value: john.doe@example.com
                    - key: phone
                      value: '5551234567'
                  addresses:
                    - addressLine1: 123 Main Street
                      addressLine2: Apt 4B
                      city: New York
                      state: NY
                      postalCode: '10001'
      responses:
        '200':
          description: Patient created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PatientResponse'
              examples:
                success:
                  summary: Successful creation
                  value:
                    success: true
                    data:
                      patient_id: 770e8400-e29b-41d4-a716-446655440002
                    message: Patient created successfully
        '400':
          description: Bad request (validation error)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                success: false
                error:
                  message: Unauthorized
  /api/external/medication-order:
    post:
      tags:
        - Medication Requests
      summary: Create Medication Request
      description: >
        Create a new medication request for a patient. This endpoint initiates
        the prescription and fulfillment process.


        **Notes:**

        - Patient and practitioner must already exist in the system

        - Medication details must be valid

        - The request will be validated against the clinic's available
        medications
      operationId: createMedicationRequest
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/MedicationRequest'
            examples:
              basic:
                summary: Create medication request
                value:
                  patient_id: 550e8400-e29b-41d4-a716-446655440001
                  practitioner_id: 550e8400-e29b-41d4-a716-446655440002
                  clinic_id: 550e8400-e29b-41d4-a716-446655440003
                  carrier_id: se-3818360
                  service_id: fedex_ground
                  is_refrigerated: true
                  medication_requests:
                    - medication: Testosterone Cypionate
                      dose: 200mg/ml
                      unit_of_measure: mg
                      quantity: 1
                      refills: '3'
                      direction: Inject 0.5ml (100mg) intramuscularly twice weekly
                      days_supply: 30
      responses:
        '200':
          description: Medication request created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MedicationRequestResponse'
              examples:
                success:
                  summary: Successful creation
                  value:
                    success: true
                    data:
                      medication_request_id: 880e8400-e29b-41d4-a716-446655440003
                    message: Medication request created successfully
        '400':
          description: Bad request (validation error)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                success: false
                error:
                  message: Unauthorized
        '404':
          description: Patient or practitioner not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /api/external/refill-request:
    post:
      tags:
        - Refills
      summary: Create Refill Request
      description: >
        Request a refill for an existing medication order that has been shipped
        or delivered.


        **Eligibility Requirements:**

        - Medication must have been shipped or delivered

        - Refills must be authorized on the original prescription

        - No pending refill request already exists


        The refill request will create a new prescription and medication order
        automatically.
      operationId: createRefillRequest
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RefillRequest'
            examples:
              basic:
                summary: Basic refill request
                value:
                  medication_request_id: 880e8400-e29b-41d4-a716-446655440003
      responses:
        '200':
          description: Refill request created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RefillResponse'
              examples:
                success:
                  summary: Successful refill request
                  value:
                    success: true
                    message: Refill request was created successfully.
                    data:
                      refill_request_id: 990e8400-e29b-41d4-a716-446655440004
                      medication_order_id: aa0e8400-e29b-41d4-a716-446655440005
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                medicationNotFound:
                  summary: Medication request not found
                  value:
                    success: false
                    error:
                      message: Medication request not found
                notEligible:
                  summary: Refill not eligible
                  value:
                    success: false
                    error:
                      message: Refills are not possible for pending medication requests
                duplicateRefill:
                  summary: Duplicate refill request
                  value:
                    success: false
                    error:
                      message: Refill request already exists
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                success: false
                error:
                  message: Unauthorized
  /api/external/carriers:
    get:
      tags:
        - Carriers
      summary: Get Carriers
      description: >
        Retrieve a list of available shipment carriers.


        Use this endpoint to get the list of carriers that can be used for
        shipping medication orders.
      operationId: getCarriers
      responses:
        '200':
          description: List of available carriers
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CarriersResponse'
              example:
                success: true
                data:
                  carriers:
                    - id: ameriship
                      name: Ameriship
                    - id: se-3818360
                      name: FedEx
                    - id: se-11225
                      name: Stamps.com
                    - id: se-11226
                      name: UPS
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                success: false
                error:
                  message: Unauthorized
  /api/external/carriers/{carrierId}/services:
    get:
      tags:
        - Carriers
      summary: Get Carrier Services
      description: >
        Retrieve available shipping services for a specific carrier based on the
        patient's location.


        This endpoint returns pricing information for each available service,
        including whether free shipping applies.
      operationId: getCarrierServices
      parameters:
        - name: carrierId
          in: path
          required: true
          description: The carrier ID (e.g., "se-3818360" for FedEx)
          schema:
            type: string
            example: se-3818360
        - name: patientId
          in: query
          required: true
          description: The patient's UUID to determine shipping location and eligibility
          schema:
            type: string
            format: uuid
            example: 01aabf3a-51cd-4180-be17-8ac9446e9ace
      responses:
        '200':
          description: List of available shipping services
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CarrierServicesResponse'
              examples:
                freeShipping:
                  summary: Free shipping available
                  value:
                    success: true
                    data:
                      - id: fedex_ground
                        name: FedEx Ground®
                        totalCost: 0
                        originalCost: 32.44
                      - id: fedex_2day
                        name: FedEx 2Day®
                        totalCost: 0
                        originalCost: 56.43
                      - id: fedex_priority_overnight
                        name: FedEx Priority Overnight®
                        totalCost: 0
                        originalCost: 118.1
                    isFreeShipment: true
                    freeShipmentType: clinic_specific
                    patientState: Alabama
                paidShipping:
                  summary: Paid shipping
                  value:
                    success: true
                    data:
                      - id: fedex_ground
                        name: FedEx Ground®
                        totalCost: 32.44
                        originalCost: 32.44
                      - id: fedex_2day
                        name: FedEx 2Day®
                        totalCost: 56.43
                        originalCost: 56.43
                    isFreeShipment: false
                    freeShipmentType: null
                    patientState: California
        '400':
          description: Service not available for this carrier/patient
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                success: false
                error:
                  message: Service not available
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                success: false
                error:
                  message: Unauthorized
  /api/external/webhook:
    post:
      tags:
        - Webhooks
      summary: Register Webhook
      description: >
        Register a webhook URL to receive real-time event notifications.


        Once registered, you will receive webhook events for:

        - Shipment creation and updates

        - Prescription status changes

        - Medication order status updates


        Webhooks are sent via HTTPS POST requests with an `x-api-key` header for
        authentication.
      operationId: createWebhook
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/WebhookRequest'
            examples:
              basic:
                summary: Basic webhook registration
                value:
                  clinic_id: 550e8400-e29b-41d4-a716-446655440000
                  webhook_url: https://partner.example.com/webhooks/novamed
      responses:
        '200':
          description: Webhook registered successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WebhookResponse'
              examples:
                success:
                  summary: Successful webhook registration
                  value:
                    success: true
                    data:
                      webhook_id: bb0e8400-e29b-41d4-a716-446655440006
                    message: Webhook created successfully
        '400':
          description: Bad request (validation error or clinic not found)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized (missing or invalid API key)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                success: false
                error:
                  message: Unauthorized
    delete:
      tags:
        - Webhooks
      summary: Delete Webhook
      description: >
        Remove a webhook configuration. The webhook will stop receiving events
        immediately.
      operationId: deleteWebhook
      parameters:
        - name: id
          in: query
          required: true
          description: Webhook ID to delete
          schema:
            type: string
            format: uuid
            example: bb0e8400-e29b-41d4-a716-446655440006
      responses:
        '200':
          description: Webhook deleted successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  message:
                    type: string
                    example: Webhook deleted successfully
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                success: false
                error:
                  message: Unauthorized
        '404':
          description: Webhook not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
components:
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: x-api-key
      description: >-
        Partner API key for authentication. Contact api@nimbus-os.com to obtain
        your API key.
  schemas:
    PractitionerRequest:
      type: object
      required:
        - first_name
        - last_name
        - email
        - npi
        - is_veterinarian
        - assigned_clinic
        - address_line_1
        - city
        - state_code
        - zip_code
      properties:
        first_name:
          type: string
          minLength: 2
          description: Practitioner's first name (minimum 2 characters)
          example: John
        last_name:
          type: string
          minLength: 2
          description: Practitioner's last name (minimum 2 characters)
          example: Doe
        email:
          type: string
          format: email
          description: Practitioner's email
          example: john.doe@example.com
        npi:
          type: string
          description: Practitioner's NPI number
          example: '1234567890'
        is_veterinarian:
          type: boolean
          description: Whether the practitioner is a veterinarian
          example: true
        assigned_clinic:
          type: string
          format: uuid
          description: ID of the assigned clinic
          example: 550e8400-e29b-41d4-a716-446655440001
        phone:
          type: string
          description: Practitioner's phone number
          example: '1234567890'
        address_line_1:
          type: string
          description: Practitioner's address line 1
          example: 123 Main St
        address_line_2:
          type: string
          description: Practitioner's address line 2
          example: Apt 1
        city:
          type: string
          description: Practitioner's city
          example: San Antonio
        state_code:
          type: string
          description: Practitioner's state code
          example: TX
        zip_code:
          type: string
          description: Practitioner's zip code
          example: '78201'
    PatientRequest:
      type: object
      required:
        - first_name
        - last_name
        - gender
        - dob
        - practitioner_id
        - assigned_clinic
        - addresses
      properties:
        first_name:
          type: string
          minLength: 2
          description: Patient's first name (minimum 2 characters)
          example: John
        middle_name:
          type: string
          nullable: true
          description: Patient's middle name (optional)
          example: Michael
        last_name:
          type: string
          description: Patient's last name
          example: Doe
        gender:
          type: string
          nullable: true
          enum:
            - male
            - female
            - other
            - unknown
          description: Patient's gender
          example: male
        dob:
          type: string
          description: Patient's date of birth
          example: '2025-07-13T18:30:00.000Z'
        species:
          type: string
          nullable: true
          enum:
            - human
            - canine
            - feline
            - equine
            - avian
            - mammal - other
            - reptilian
            - swine
          description: Patient's species (for veterinary use)
          example: human
        animal_owner_name:
          type: string
          nullable: true
          description: Animal owner's name (for veterinary use)
          example: Jane Smith
        weight:
          type: string
          nullable: true
          description: Patient's weight
          example: '70.5'
        weight_recorded_date:
          type: string
          nullable: true
          description: Date when weight was recorded
          example: '2024-01-15'
        status:
          type: string
          nullable: true
          enum:
            - active
            - inactive
          description: Patient's status
          example: active
        practitioner_id:
          type: string
          format: uuid
          description: ID of the assigned practitioner
          example: 550e8400-e29b-41d4-a716-446655440001
        assigned_clinic:
          type: string
          format: uuid
          description: ID of the assigned clinic
          example: 550e8400-e29b-41d4-a716-446655440002
        contacts:
          type: array
          description: Array of contact information
          items:
            type: object
            properties:
              key:
                type: string
                enum:
                  - email
                  - phone
                  - url
                  - sms
                  - fax
                description: Contact type (email, phone, url, etc.)
                example: email
              value:
                type: string
                description: Contact value (validated based on key type)
                example: john.doe@example.com
          example:
            - key: email
              value: john.doe@example.com
            - key: phone
              value: '5551234567'
        addresses:
          type: array
          description: Array of patient addresses (currently only supports single address)
          items:
            type: object
            required:
              - addressLine1
              - city
              - state
              - postalCode
            properties:
              addressLine1:
                type: string
                nullable: true
                description: First line of address
                example: 123 Main Street
              addressLine2:
                type: string
                nullable: true
                description: Second line of address
                example: Apt 4B
              addressLine3:
                type: string
                nullable: true
                description: Third line of address
                example: Building C
              city:
                type: string
                nullable: true
                description: City name
                example: New York
              state:
                type: string
                nullable: true
                description: State or province
                example: NY
              postalCode:
                type: string
                nullable: true
                description: Postal/ZIP code
                example: '10001'
          example:
            - addressLine1: 123 Main Street
              addressLine2: Apt 4B
              city: New York
              state: NY
              postalCode: '10001'
    MedicationRequest:
      type: object
      required:
        - patient_id
        - practitioner_id
        - clinic_id
        - carrier_id
        - service_id
        - medication_requests
      properties:
        patient_id:
          type: string
          format: uuid
          description: ID of the patient
          example: 550e8400-e29b-41d4-a716-446655440001
        practitioner_id:
          type: string
          format: uuid
          description: ID of the practitioner
          example: 550e8400-e29b-41d4-a716-446655440001
        clinic_id:
          type: string
          format: uuid
          description: ID of the clinic
          example: 550e8400-e29b-41d4-a716-446655440001
        carrier_id:
          type: string
          description: ID of the shipping carrier (from GET /api/external/carriers)
          example: se-3818360
        service_id:
          type: string
          description: >-
            ID of the shipping service (from GET
            /api/external/carriers/{carrierId}/services)
          example: fedex_ground
        is_refrigerated:
          type: boolean
          description: Is refrigerated
          example: true
        shipment_group_id:
          type: string
          description: Shipment group ID
          example: 550e8400-e29b-41d4-a716-446655440001
        medication_requests:
          type: array
          description: Array of medication requests
          items:
            type: object
            required:
              - medication
              - dose
              - quantity
              - direction
            properties:
              medication:
                type: string
                description: Name of the medication
                example: Aspirin
              dose:
                type: string
                description: Dose of the medication
                example: 100mg
              unit_of_measure:
                type: string
                description: >-
                  Unit of measure (recommended). If omitted, NovaMed will
                  attempt to derive this from the dose string (e.g. "0.25 mg" ->
                  "mg").
                example: mg
              quantity:
                type: number
                description: Quantity of the medication
                example: 100
              refills:
                type: string
                description: Number of refills
                example: '3'
              direction:
                type: string
                description: Direction of the medication
                example: Take 1 tablet by mouth daily
              days_supply:
                type: number
                description: Days supply
                example: 30
              flavor:
                type: string
                description: Flavor of the medication
                example: Orange
              notes:
                type: string
                description: Notes for the medication
                example: Patient has a history of allergies
              do_not_refill:
                type: boolean
                description: Do not refill
                example: true
              do_not_fill:
                type: boolean
                description: Do not fill
                example: true
              patient_contact_requested:
                type: boolean
                description: Patient contact requested
                example: true
              reason_for_compounding:
                type: string
                description: Reason for compounding
                example: Patient has a history of allergies
              reason_for_compounding_additional_context:
                type: string
                description: Additional context for reason for compounding
                example: Patient has a history of allergies
    RefillRequest:
      type: object
      required:
        - medication_request_id
      properties:
        medication_request_id:
          type: string
          format: uuid
          description: UUID of the medication request to refill
          example: 880e8400-e29b-41d4-a716-446655440003
        shipment_group_id:
          type: string
          description: Optional shipment group ID for grouping multiple refills
          example: optional-group-id
    WebhookRequest:
      type: object
      required:
        - clinic_id
        - webhook_url
      properties:
        clinic_id:
          type: string
          format: uuid
          description: UUID of the clinic associated with this webhook
          example: 550e8400-e29b-41d4-a716-446655440000
        webhook_url:
          type: string
          format: uri
          description: HTTPS URL where webhook events will be sent
          example: https://partner.example.com/webhooks/novamed
    PractitionerResponse:
      type: object
      properties:
        success:
          type: boolean
          example: true
        data:
          type: object
          properties:
            practitioner_id:
              type: string
              format: uuid
              description: Unique identifier for the created practitioner
              example: 660e8400-e29b-41d4-a716-446655440001
        message:
          type: string
          example: Practitioner created successfully
    PatientResponse:
      type: object
      properties:
        success:
          type: boolean
          example: true
        data:
          type: object
          properties:
            patient_id:
              type: string
              format: uuid
              description: Unique identifier for the created patient
              example: 770e8400-e29b-41d4-a716-446655440002
        message:
          type: string
          example: Patient created successfully
    MedicationRequestResponse:
      type: object
      properties:
        success:
          type: boolean
          example: true
        data:
          type: object
          properties:
            medication_request_id:
              type: string
              format: uuid
              description: Unique identifier for the medication request
              example: 880e8400-e29b-41d4-a716-446655440003
        message:
          type: string
          example: Medication request created successfully
    RefillResponse:
      type: object
      properties:
        success:
          type: boolean
          example: true
        message:
          type: string
          example: Refill request was created successfully.
        data:
          type: object
          properties:
            refill_request_id:
              type: string
              format: uuid
              description: Unique identifier for the refill request
              example: 990e8400-e29b-41d4-a716-446655440004
            medication_order_id:
              type: string
              format: uuid
              description: Unique identifier for the new medication order
              example: aa0e8400-e29b-41d4-a716-446655440005
    CarriersResponse:
      type: object
      properties:
        success:
          type: boolean
          example: true
        data:
          type: object
          properties:
            carriers:
              type: array
              description: List of available shipment carriers
              items:
                type: object
                properties:
                  id:
                    type: string
                    description: Unique identifier for the carrier
                    example: ameriship
                  name:
                    type: string
                    description: Display name of the carrier
                    example: Ameriship
    CarrierServicesResponse:
      type: object
      properties:
        success:
          type: boolean
          example: true
        data:
          type: array
          description: List of available shipping services
          items:
            type: object
            properties:
              id:
                type: string
                description: Unique identifier for the service
                example: fedex_ground
              name:
                type: string
                description: Display name of the service
                example: FedEx Ground®
              totalCost:
                type: number
                description: Cost to charge (0 if free shipping applies)
                example: 0
              originalCost:
                type: number
                description: Original cost before any discounts
                example: 32.44
        isFreeShipment:
          type: boolean
          description: Whether free shipping applies for this patient
          example: true
        freeShipmentType:
          type: string
          nullable: true
          description: Type of free shipment (e.g., "clinic_specific") or null if not free
          example: clinic_specific
        patientState:
          type: string
          description: The patient's state used for shipping calculation
          example: Alabama
    WebhookResponse:
      type: object
      properties:
        success:
          type: boolean
          example: true
        data:
          type: object
          properties:
            webhook_id:
              type: string
              format: uuid
              description: Unique identifier for the registered webhook
              example: bb0e8400-e29b-41d4-a716-446655440006
        message:
          type: string
          example: Webhook created successfully
    ErrorResponse:
      type: object
      properties:
        success:
          type: boolean
          example: false
        error:
          type: object
          properties:
            message:
              type: string
              description: Human-readable error message
              example: Validation error
            details:
              type: object
              description: Additional error details
              example: {}
    WebhookEvent:
      type: object
      description: Base structure for all webhook events sent to partners
      properties:
        event_name:
          type: string
          description: Type of webhook event
          enum:
            - medication_order:verified
            - medication_order:submitted
            - medication_order:acknowledged
            - medication_order:filled
            - shipment:created
            - shipment:cancelled
            - practitioner:activated
        event_data:
          type: object
          description: Event-specific data payload
    MedicationOrderEvent:
      allOf:
        - $ref: '#/components/schemas/WebhookEvent'
        - type: object
          description: Webhook event for medication order status changes
          properties:
            event_name:
              type: string
              example: medication_order:verified
            event_data:
              type: object
              properties:
                id:
                  type: string
                  format: uuid
                  description: Unique identifier for the medication order
                  example: a7570e3c-4338-485f-9465-ee09793c2d46
                clinic_id:
                  type: string
                  format: uuid
                  description: Clinic identifier
                  example: 2a7d8da1-2f69-46e1-87a4-04490ab73c41
                patient_id:
                  type: string
                  format: uuid
                  description: Patient identifier
                  example: 8456ce26-05db-4fcd-bebd-495bd7bc04df
                practitioner_id:
                  type: string
                  format: uuid
                  description: Practitioner identifier
                  example: a7570e3c-4338-485f-9465-ee09793c2d46
                rx_number:
                  type: string
                  description: Prescription number (not available for all events)
                  example: '123456'
    ShipmentCreatedEvent:
      allOf:
        - $ref: '#/components/schemas/WebhookEvent'
        - type: object
          description: Webhook event when a shipment is created
          properties:
            event_name:
              type: string
              example: shipment:created
            event_data:
              type: object
              properties:
                id:
                  type: string
                  format: uuid
                  description: Unique identifier for the medication order
                  example: a7570e3c-4338-485f-9465-ee09793c2d46
                clinic_id:
                  type: string
                  format: uuid
                  description: Clinic identifier
                  example: 2a7d8da1-2f69-46e1-87a4-04490ab73c41
                patient_id:
                  type: string
                  format: uuid
                  description: Patient identifier
                  example: 8456ce26-05db-4fcd-bebd-495bd7bc04df
                practitioner_id:
                  type: string
                  format: uuid
                  description: Practitioner identifier
                  example: a7570e3c-4338-485f-9465-ee09793c2d46
                rx_number:
                  type: string
                  description: Prescription number
                  example: '123456'
                shipping_label:
                  type: string
                  format: uri
                  description: URL to the shipping label PDF
                  example: https://example.com/shipping-label.pdf
                shipment_id:
                  type: string
                  format: uuid
                  description: Unique identifier for the shipment
                  example: 8456ce26-05db-4fcd-bebd-495bd7bc04df
                shipment_provider:
                  type: string
                  description: Shipping provider name
                  example: Ameriship
                tracking_url:
                  type: string
                  format: uri
                  description: URL to track the shipment
                  example: https://example.com/tracking
    PractitionerActivatedEvent:
      allOf:
        - $ref: '#/components/schemas/WebhookEvent'
        - type: object
          description: Webhook event when a practitioner is activated
          properties:
            event_name:
              type: string
              example: practitioner:activated
            event_data:
              type: object
              properties:
                practitioner_id:
                  type: string
                  format: uuid
                  description: Unique identifier for the practitioner
                  example: 4f407bca-2a9b-4dde-8240-e53331a5a986
                practitioner_name:
                  type: string
                  description: Full name of the practitioner
                  example: Dr. John Smith
                practitioner_email:
                  type: string
                  format: email
                  description: Practitioner's email address
                  example: dr.smith@clinic.com
                practitioner_phone:
                  type: string
                  nullable: true
                  description: Practitioner's phone number
                  example: +1-555-0123
                practitioner_npi:
                  type: string
                  description: Practitioner's NPI number
                  example: '1234567890'
                practitioner_status:
                  type: string
                  description: Practitioner's current status
                  example: active
