{
  "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.\n\n**Authentication:** All requests require an `x-api-key` header with your API key.\n\n**Base URLs:**\n- Development: `https://novamed-feapidev.nimbushealthcaretest.com`\n- Production: `https://feapi.novamed.care`\n\nFor detailed guides, see the [Getting Started](/guides/quickstart) documentation.\n",
    "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.\n\n**Notes:**\n- All required fields must be provided and valid\n- `assigned_clinic` must reference an existing clinic UUID\n- Validation errors will return descriptive messages for each field\n",
        "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.\n\n**Notes:**\n- All required fields must be provided\n- `clinic_id` must reference an existing clinic UUID\n- Address information is required for shipping\n",
        "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.\n\n**Notes:**\n- Patient and practitioner must already exist in the system\n- Medication details must be valid\n- The request will be validated against the clinic's available medications\n",
        "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.\n\n**Eligibility Requirements:**\n- Medication must have been shipped or delivered\n- Refills must be authorized on the original prescription\n- No pending refill request already exists\n\nThe refill request will create a new prescription and medication order automatically.\n",
        "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.\n\nUse this endpoint to get the list of carriers that can be used for shipping medication orders.\n",
        "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.\n\nThis endpoint returns pricing information for each available service, including whether free shipping applies.\n",
        "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.\n\nOnce registered, you will receive webhook events for:\n- Shipment creation and updates\n- Prescription status changes\n- Medication order status updates\n\nWebhooks are sent via HTTPS POST requests with an `x-api-key` header for authentication.\n",
        "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.\n",
        "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"
                  }
                }
              }
            }
          }
        ]
      }
    }
  }
}