{
  "openapi": "3.1.0",
  "info": {
    "title": "Formisoft API",
    "description": "Healthcare practice management API. Manage forms, patients, appointments, submissions, webhooks, and workflows programmatically.",
    "version": "1.0.0",
    "contact": {
      "name": "Formisoft",
      "url": "https://formisoft.com/developers",
      "email": "vincent@formisoft.com"
    }
  },
  "servers": [
    {
      "url": "https://formisoft.com/api",
      "description": "Production"
    }
  ],
  "security": [
    {
      "bearerAuth": []
    }
  ],
  "paths": {
    "/v1/auth/test": {
      "get": {
        "operationId": "testAuth",
        "summary": "Test API key",
        "description": "Verify that your API key is valid and see which organization it belongs to.",
        "tags": ["Auth"],
        "responses": {
          "200": {
            "description": "API key is valid",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "ok": { "type": "boolean" },
                    "organizationId": { "type": "string" },
                    "organizationName": { "type": "string" }
                  }
                }
              }
            }
          },
          "401": { "$ref": "#/components/responses/Unauthorized" }
        }
      }
    },
    "/forms": {
      "get": {
        "operationId": "listForms",
        "summary": "List forms",
        "description": "List all forms for your organization, sorted by last updated.",
        "tags": ["Forms"],
        "responses": {
          "200": {
            "description": "List of forms",
            "content": {
              "application/json": {
                "schema": {
                  "type": "array",
                  "items": { "$ref": "#/components/schemas/Form" }
                }
              }
            }
          },
          "401": { "$ref": "#/components/responses/Unauthorized" }
        }
      },
      "post": {
        "operationId": "createForm",
        "summary": "Create a form",
        "description": "Create a new form. It starts in draft status.",
        "tags": ["Forms"],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["name"],
                "properties": {
                  "name": { "type": "string", "description": "Form name" },
                  "description": { "type": "string", "description": "Form description" },
                  "category": { "type": "string", "default": "intake", "description": "Form category" },
                  "pages": { "type": "array", "description": "Form pages with fields" },
                  "settings": { "type": "object", "description": "Form settings (notifications, redirect, etc.)" },
                  "branding": { "type": "object", "description": "Form branding (logo, colors, etc.)" }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Created form",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/Form" }
              }
            }
          },
          "400": { "$ref": "#/components/responses/BadRequest" },
          "401": { "$ref": "#/components/responses/Unauthorized" }
        }
      }
    },
    "/forms/{id}": {
      "get": {
        "operationId": "getForm",
        "summary": "Get a form",
        "description": "Get a single form by ID, including submission count.",
        "tags": ["Forms"],
        "parameters": [
          { "$ref": "#/components/parameters/ResourceId" }
        ],
        "responses": {
          "200": {
            "description": "Form details",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/Form" }
              }
            }
          },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "404": { "$ref": "#/components/responses/NotFound" }
        }
      },
      "put": {
        "operationId": "updateForm",
        "summary": "Update a form",
        "description": "Update a form. Only include fields you want to change. Set status to 'published' to publish.",
        "tags": ["Forms"],
        "parameters": [
          { "$ref": "#/components/parameters/ResourceId" }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "name": { "type": "string" },
                  "description": { "type": "string" },
                  "category": { "type": "string" },
                  "status": { "type": "string", "enum": ["draft", "published", "archived"] },
                  "pages": { "type": "array" },
                  "settings": { "type": "object" },
                  "branding": { "type": "object" }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Updated form",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/Form" }
              }
            }
          },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "403": { "$ref": "#/components/responses/Forbidden" },
          "404": { "$ref": "#/components/responses/NotFound" }
        }
      },
      "delete": {
        "operationId": "deleteForm",
        "summary": "Delete a form",
        "description": "Permanently delete a form and all its submissions.",
        "tags": ["Forms"],
        "parameters": [
          { "$ref": "#/components/parameters/ResourceId" }
        ],
        "responses": {
          "200": { "$ref": "#/components/responses/Success" },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "403": { "$ref": "#/components/responses/Forbidden" },
          "404": { "$ref": "#/components/responses/NotFound" }
        }
      }
    },
    "/patients": {
      "get": {
        "operationId": "listPatients",
        "summary": "List patients",
        "description": "List patients for your organization. Supports search across name, email, and phone.",
        "tags": ["Patients"],
        "parameters": [
          {
            "name": "search",
            "in": "query",
            "description": "Search term for name, email, or phone",
            "schema": { "type": "string" }
          },
          {
            "name": "status",
            "in": "query",
            "description": "Filter by patient status",
            "schema": { "type": "string", "enum": ["active", "inactive", "archived"] }
          }
        ],
        "responses": {
          "200": {
            "description": "List of patients",
            "content": {
              "application/json": {
                "schema": {
                  "type": "array",
                  "items": { "$ref": "#/components/schemas/Patient" }
                }
              }
            }
          },
          "401": { "$ref": "#/components/responses/Unauthorized" }
        }
      },
      "post": {
        "operationId": "createPatient",
        "summary": "Create a patient",
        "description": "Create a new patient record.",
        "tags": ["Patients"],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["firstName", "lastName"],
                "properties": {
                  "firstName": { "type": "string" },
                  "lastName": { "type": "string" },
                  "email": { "type": "string", "format": "email" },
                  "phone": { "type": "string" },
                  "dateOfBirth": { "type": "string", "format": "date" },
                  "gender": { "type": "string" },
                  "address": { "type": "object" },
                  "insuranceCarrier": { "type": "string" },
                  "insurancePolicyNumber": { "type": "string" },
                  "insuranceGroupNumber": { "type": "string" },
                  "insuranceSubscriber": { "type": "string" },
                  "emergencyContactName": { "type": "string" },
                  "emergencyContactPhone": { "type": "string" },
                  "emergencyContactRelationship": { "type": "string" }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Created patient",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/Patient" }
              }
            }
          },
          "400": { "$ref": "#/components/responses/BadRequest" },
          "401": { "$ref": "#/components/responses/Unauthorized" }
        }
      }
    },
    "/patients/{id}": {
      "get": {
        "operationId": "getPatient",
        "summary": "Get a patient",
        "description": "Get a single patient with medical data, recent appointments, submissions, and documents.",
        "tags": ["Patients"],
        "parameters": [
          { "$ref": "#/components/parameters/ResourceId" }
        ],
        "responses": {
          "200": {
            "description": "Patient details",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/Patient" }
              }
            }
          },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "404": { "$ref": "#/components/responses/NotFound" }
        }
      },
      "put": {
        "operationId": "updatePatient",
        "summary": "Update a patient",
        "description": "Update a patient record. Only include fields you want to change.",
        "tags": ["Patients"],
        "parameters": [
          { "$ref": "#/components/parameters/ResourceId" }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "firstName": { "type": "string" },
                  "lastName": { "type": "string" },
                  "email": { "type": "string", "format": "email" },
                  "phone": { "type": "string" },
                  "dateOfBirth": { "type": "string", "format": "date" },
                  "gender": { "type": "string" },
                  "status": { "type": "string", "enum": ["active", "inactive", "archived"] },
                  "address": { "type": "object" },
                  "insuranceCarrier": { "type": "string" },
                  "insurancePolicyNumber": { "type": "string" },
                  "insuranceGroupNumber": { "type": "string" },
                  "insuranceSubscriber": { "type": "string" },
                  "emergencyContactName": { "type": "string" },
                  "emergencyContactPhone": { "type": "string" },
                  "emergencyContactRelationship": { "type": "string" }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Updated patient",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/Patient" }
              }
            }
          },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "403": { "$ref": "#/components/responses/Forbidden" },
          "404": { "$ref": "#/components/responses/NotFound" }
        }
      },
      "delete": {
        "operationId": "deletePatient",
        "summary": "Delete a patient",
        "description": "Permanently delete a patient record.",
        "tags": ["Patients"],
        "parameters": [
          { "$ref": "#/components/parameters/ResourceId" }
        ],
        "responses": {
          "200": { "$ref": "#/components/responses/Success" },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "403": { "$ref": "#/components/responses/Forbidden" },
          "404": { "$ref": "#/components/responses/NotFound" }
        }
      }
    },
    "/appointments": {
      "get": {
        "operationId": "listAppointments",
        "summary": "List appointments",
        "description": "List appointments for your organization, sorted by most recent.",
        "tags": ["Appointments"],
        "parameters": [
          {
            "name": "from",
            "in": "query",
            "description": "Start date filter (ISO datetime)",
            "schema": { "type": "string", "format": "date-time" }
          },
          {
            "name": "to",
            "in": "query",
            "description": "End date filter (ISO datetime)",
            "schema": { "type": "string", "format": "date-time" }
          },
          {
            "name": "providerId",
            "in": "query",
            "description": "Filter by provider ID",
            "schema": { "type": "string" }
          }
        ],
        "responses": {
          "200": {
            "description": "List of appointments",
            "content": {
              "application/json": {
                "schema": {
                  "type": "array",
                  "items": { "$ref": "#/components/schemas/Appointment" }
                }
              }
            }
          },
          "401": { "$ref": "#/components/responses/Unauthorized" }
        }
      },
      "post": {
        "operationId": "createAppointment",
        "summary": "Create an appointment",
        "description": "Create an appointment. Automatically checks for scheduling conflicts.",
        "tags": ["Appointments"],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["patientId", "scheduledAt"],
                "properties": {
                  "patientId": { "type": "string", "description": "Patient ID" },
                  "scheduledAt": { "type": "string", "format": "date-time", "description": "Appointment date/time (ISO)" },
                  "providerId": { "type": "string", "description": "Provider member ID" },
                  "duration": { "type": "integer", "default": 30, "description": "Duration in minutes" },
                  "type": { "type": "string", "description": "Appointment type (e.g. initial_consultation, follow_up)" },
                  "notes": { "type": "string" },
                  "formIds": { "type": "array", "items": { "type": "string" }, "description": "Intake form IDs to attach" },
                  "autoSendIntake": { "type": "boolean", "description": "Email intake forms to patient" }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Created appointment",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/Appointment" }
              }
            }
          },
          "400": { "$ref": "#/components/responses/BadRequest" },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "409": {
            "description": "Scheduling conflict",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/Error" }
              }
            }
          }
        }
      }
    },
    "/appointments/{id}": {
      "get": {
        "operationId": "getAppointment",
        "summary": "Get an appointment",
        "description": "Get a single appointment with patient, provider, and form details.",
        "tags": ["Appointments"],
        "parameters": [
          { "$ref": "#/components/parameters/ResourceId" }
        ],
        "responses": {
          "200": {
            "description": "Appointment details",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/Appointment" }
              }
            }
          },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "404": { "$ref": "#/components/responses/NotFound" }
        }
      },
      "put": {
        "operationId": "updateAppointment",
        "summary": "Update an appointment",
        "description": "Update an appointment. Supports rescheduling (with conflict detection) and status transitions. Valid transitions: scheduled > confirmed/checked_in/cancelled/completed/no_show, confirmed > scheduled/checked_in/cancelled/completed/no_show, checked_in > in_progress/cancelled/completed/no_show, in_progress > completed/cancelled, cancelled > scheduled, no_show > scheduled.",
        "tags": ["Appointments"],
        "parameters": [
          { "$ref": "#/components/parameters/ResourceId" }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "scheduledAt": { "type": "string", "format": "date-time" },
                  "duration": { "type": "integer" },
                  "type": { "type": "string" },
                  "status": { "type": "string", "enum": ["scheduled", "confirmed", "checked_in", "in_progress", "completed", "cancelled", "no_show"] },
                  "notes": { "type": "string" },
                  "cancelReason": { "type": "string", "description": "Required when status is 'cancelled'" }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Updated appointment",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/Appointment" }
              }
            }
          },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "404": { "$ref": "#/components/responses/NotFound" },
          "409": {
            "description": "Scheduling conflict",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/Error" }
              }
            }
          },
          "422": {
            "description": "Invalid status transition",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/Error" }
              }
            }
          }
        }
      },
      "delete": {
        "operationId": "deleteAppointment",
        "summary": "Delete an appointment",
        "description": "Permanently delete an appointment.",
        "tags": ["Appointments"],
        "parameters": [
          { "$ref": "#/components/parameters/ResourceId" }
        ],
        "responses": {
          "200": { "$ref": "#/components/responses/Success" },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "403": { "$ref": "#/components/responses/Forbidden" },
          "404": { "$ref": "#/components/responses/NotFound" }
        }
      }
    },
    "/submissions": {
      "get": {
        "operationId": "listSubmissions",
        "summary": "List submissions",
        "description": "List form submissions. Filter by form or status.",
        "tags": ["Submissions"],
        "parameters": [
          {
            "name": "formId",
            "in": "query",
            "description": "Filter by form ID",
            "schema": { "type": "string" }
          },
          {
            "name": "status",
            "in": "query",
            "description": "Filter by status",
            "schema": { "type": "string", "enum": ["submitted", "reviewed", "flagged"] }
          },
          {
            "name": "limit",
            "in": "query",
            "description": "Max results (default 100, max 1000, or 'all')",
            "schema": { "type": "string" }
          }
        ],
        "responses": {
          "200": {
            "description": "List of submissions",
            "content": {
              "application/json": {
                "schema": {
                  "type": "array",
                  "items": { "$ref": "#/components/schemas/Submission" }
                }
              }
            }
          },
          "401": { "$ref": "#/components/responses/Unauthorized" }
        }
      },
      "patch": {
        "operationId": "reviewSubmission",
        "summary": "Review a submission",
        "description": "Update a submission's review status.",
        "tags": ["Submissions"],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["submissionId", "status"],
                "properties": {
                  "submissionId": { "type": "string" },
                  "status": { "type": "string", "enum": ["submitted", "reviewed", "flagged"] },
                  "reviewNotes": { "type": "string" }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Updated submission",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/Submission" }
              }
            }
          },
          "401": { "$ref": "#/components/responses/Unauthorized" }
        }
      }
    },
    "/submissions/{id}": {
      "patch": {
        "operationId": "reviewSubmissionById",
        "summary": "Review a submission by ID",
        "description": "Update a submission's review status by its ID.",
        "tags": ["Submissions"],
        "parameters": [
          { "$ref": "#/components/parameters/ResourceId" }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["status"],
                "properties": {
                  "status": { "type": "string", "enum": ["submitted", "reviewed", "flagged"] },
                  "reviewNotes": { "type": "string" }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Updated submission",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/Submission" }
              }
            }
          },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "404": { "$ref": "#/components/responses/NotFound" }
        }
      },
      "delete": {
        "operationId": "deleteSubmission",
        "summary": "Delete a submission",
        "description": "Permanently delete a submission.",
        "tags": ["Submissions"],
        "parameters": [
          { "$ref": "#/components/parameters/ResourceId" }
        ],
        "responses": {
          "200": { "$ref": "#/components/responses/Success" },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "404": { "$ref": "#/components/responses/NotFound" }
        }
      }
    },
    "/webhooks": {
      "get": {
        "operationId": "listWebhooks",
        "summary": "List webhooks",
        "description": "List all webhook configurations for your organization.",
        "tags": ["Webhooks"],
        "responses": {
          "200": {
            "description": "List of webhooks",
            "content": {
              "application/json": {
                "schema": {
                  "type": "array",
                  "items": { "$ref": "#/components/schemas/WebhookConfig" }
                }
              }
            }
          },
          "401": { "$ref": "#/components/responses/Unauthorized" }
        }
      },
      "post": {
        "operationId": "createWebhook",
        "summary": "Create a webhook",
        "description": "Create a new webhook configuration. The signing secret is returned once at creation.",
        "tags": ["Webhooks"],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["url", "events"],
                "properties": {
                  "url": { "type": "string", "format": "uri", "description": "Webhook URL (HTTPS recommended)" },
                  "events": { "type": "array", "items": { "type": "string" }, "description": "Event types to subscribe to" }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Created webhook with signing secret",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "id": { "type": "string" },
                    "secret": { "type": "string", "description": "HMAC signing secret (shown once)" }
                  }
                }
              }
            }
          },
          "400": { "$ref": "#/components/responses/BadRequest" },
          "401": { "$ref": "#/components/responses/Unauthorized" }
        }
      }
    },
    "/webhooks/{id}": {
      "put": {
        "operationId": "updateWebhook",
        "summary": "Update a webhook",
        "description": "Update a webhook configuration.",
        "tags": ["Webhooks"],
        "parameters": [
          { "$ref": "#/components/parameters/ResourceId" }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "url": { "type": "string", "format": "uri" },
                  "events": { "type": "array", "items": { "type": "string" } },
                  "active": { "type": "boolean" }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Updated webhook",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/WebhookConfig" }
              }
            }
          },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "404": { "$ref": "#/components/responses/NotFound" }
        }
      },
      "delete": {
        "operationId": "deleteWebhook",
        "summary": "Delete a webhook",
        "description": "Delete a webhook configuration and all its delivery history.",
        "tags": ["Webhooks"],
        "parameters": [
          { "$ref": "#/components/parameters/ResourceId" }
        ],
        "responses": {
          "200": { "$ref": "#/components/responses/Success" },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "404": { "$ref": "#/components/responses/NotFound" }
        }
      }
    },
    "/workflows": {
      "get": {
        "operationId": "listWorkflows",
        "summary": "List workflows",
        "description": "List all workflow configurations for your organization.",
        "tags": ["Workflows"],
        "responses": {
          "200": {
            "description": "List of workflows",
            "content": {
              "application/json": {
                "schema": {
                  "type": "array",
                  "items": { "$ref": "#/components/schemas/Workflow" }
                }
              }
            }
          },
          "401": { "$ref": "#/components/responses/Unauthorized" }
        }
      },
      "put": {
        "operationId": "upsertWorkflow",
        "summary": "Upsert a workflow",
        "description": "Create or update a workflow configuration by type.",
        "tags": ["Workflows"],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["type"],
                "properties": {
                  "type": { "type": "string", "enum": ["appointment_reminder", "intake_reminder", "post_visit_review", "no_show_followup"], "description": "Workflow type" },
                  "enabled": { "type": "boolean", "default": true },
                  "config": { "type": "object", "description": "Workflow-specific configuration (delays, templates, etc.)" }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Upserted workflow",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/Workflow" }
              }
            }
          },
          "400": { "$ref": "#/components/responses/BadRequest" },
          "401": { "$ref": "#/components/responses/Unauthorized" }
        }
      }
    },
    "/analytics": {
      "get": {
        "operationId": "getAnalytics",
        "summary": "Get form analytics",
        "description": "Get analytics data for a form (view locations).",
        "tags": ["Analytics"],
        "parameters": [
          {
            "name": "formId",
            "in": "query",
            "required": true,
            "description": "The form ID to get analytics for",
            "schema": { "type": "string" }
          }
        ],
        "responses": {
          "200": {
            "description": "Analytics data",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "latitude": { "type": "number" },
                          "longitude": { "type": "number" },
                          "city": { "type": "string" },
                          "region": { "type": "string" },
                          "country": { "type": "string" }
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "400": { "$ref": "#/components/responses/BadRequest" },
          "401": { "$ref": "#/components/responses/Unauthorized" }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "bearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "description": "API key with fsk_ prefix. Create in Settings > API Keys."
      }
    },
    "parameters": {
      "ResourceId": {
        "name": "id",
        "in": "path",
        "required": true,
        "description": "Resource ID",
        "schema": { "type": "string" }
      }
    },
    "schemas": {
      "Form": {
        "type": "object",
        "properties": {
          "id": { "type": "string" },
          "name": { "type": "string" },
          "description": { "type": "string" },
          "category": { "type": "string" },
          "status": { "type": "string", "enum": ["draft", "published", "archived"] },
          "pages": { "type": "array" },
          "settings": { "type": "object" },
          "branding": { "type": "object" },
          "_count": {
            "type": "object",
            "properties": {
              "submissions": { "type": "integer" }
            }
          },
          "createdAt": { "type": "string", "format": "date-time" },
          "updatedAt": { "type": "string", "format": "date-time" }
        }
      },
      "Patient": {
        "type": "object",
        "properties": {
          "id": { "type": "string" },
          "patientId": { "type": "string", "description": "Human-readable ID (e.g. PAT-000001)" },
          "firstName": { "type": "string" },
          "lastName": { "type": "string" },
          "email": { "type": "string" },
          "phone": { "type": "string" },
          "dateOfBirth": { "type": "string", "format": "date-time" },
          "gender": { "type": "string" },
          "status": { "type": "string", "enum": ["active", "inactive", "archived"] },
          "address": { "type": "object" },
          "insuranceCarrier": { "type": "string" },
          "insurancePolicyNumber": { "type": "string" },
          "insuranceGroupNumber": { "type": "string" },
          "emergencyContactName": { "type": "string" },
          "emergencyContactPhone": { "type": "string" },
          "emergencyContactRelationship": { "type": "string" },
          "_count": {
            "type": "object",
            "properties": {
              "appointments": { "type": "integer" },
              "submissions": { "type": "integer" }
            }
          },
          "createdAt": { "type": "string", "format": "date-time" }
        }
      },
      "Appointment": {
        "type": "object",
        "properties": {
          "id": { "type": "string" },
          "patientId": { "type": "string" },
          "providerId": { "type": "string" },
          "scheduledAt": { "type": "string", "format": "date-time" },
          "duration": { "type": "integer", "description": "Duration in minutes" },
          "type": { "type": "string" },
          "status": { "type": "string", "enum": ["scheduled", "confirmed", "checked_in", "in_progress", "completed", "cancelled", "no_show"] },
          "notes": { "type": "string" },
          "cancelReason": { "type": "string" },
          "cancelledAt": { "type": "string", "format": "date-time" },
          "patient": { "$ref": "#/components/schemas/Patient" },
          "createdAt": { "type": "string", "format": "date-time" }
        }
      },
      "Submission": {
        "type": "object",
        "properties": {
          "id": { "type": "string" },
          "formId": { "type": "string" },
          "status": { "type": "string", "enum": ["submitted", "reviewed", "flagged"] },
          "data": { "type": "object", "description": "Key-value map of field IDs to submitted values" },
          "form": {
            "type": "object",
            "properties": {
              "id": { "type": "string" },
              "name": { "type": "string" }
            }
          },
          "patient": {
            "type": "object",
            "properties": {
              "id": { "type": "string" },
              "firstName": { "type": "string" },
              "lastName": { "type": "string" }
            }
          },
          "reviewedAt": { "type": "string", "format": "date-time" },
          "reviewNotes": { "type": "string" },
          "createdAt": { "type": "string", "format": "date-time" }
        }
      },
      "WebhookConfig": {
        "type": "object",
        "properties": {
          "id": { "type": "string" },
          "url": { "type": "string" },
          "events": { "type": "array", "items": { "type": "string" } },
          "active": { "type": "boolean" },
          "_count": {
            "type": "object",
            "properties": {
              "deliveries": { "type": "integer" }
            }
          },
          "createdAt": { "type": "string", "format": "date-time" }
        }
      },
      "Workflow": {
        "type": "object",
        "properties": {
          "id": { "type": "string" },
          "type": { "type": "string", "enum": ["appointment_reminder", "intake_reminder", "post_visit_review", "no_show_followup"] },
          "enabled": { "type": "boolean" },
          "config": { "type": "object" },
          "createdAt": { "type": "string", "format": "date-time" },
          "updatedAt": { "type": "string", "format": "date-time" }
        }
      },
      "Error": {
        "type": "object",
        "properties": {
          "error": { "type": "string" }
        }
      }
    },
    "responses": {
      "Success": {
        "description": "Operation successful",
        "content": {
          "application/json": {
            "schema": {
              "type": "object",
              "properties": {
                "success": { "type": "boolean" }
              }
            }
          }
        }
      },
      "BadRequest": {
        "description": "Bad request",
        "content": {
          "application/json": {
            "schema": { "$ref": "#/components/schemas/Error" }
          }
        }
      },
      "Unauthorized": {
        "description": "Unauthorized - invalid or missing API key",
        "content": {
          "application/json": {
            "schema": { "$ref": "#/components/schemas/Error" }
          }
        }
      },
      "Forbidden": {
        "description": "Forbidden - insufficient permissions",
        "content": {
          "application/json": {
            "schema": { "$ref": "#/components/schemas/Error" }
          }
        }
      },
      "NotFound": {
        "description": "Resource not found",
        "content": {
          "application/json": {
            "schema": { "$ref": "#/components/schemas/Error" }
          }
        }
      }
    }
  },
  "tags": [
    { "name": "Auth", "description": "API key verification" },
    { "name": "Forms", "description": "Create and manage intake forms" },
    { "name": "Patients", "description": "Patient record management" },
    { "name": "Appointments", "description": "Appointment scheduling" },
    { "name": "Submissions", "description": "Form submission review" },
    { "name": "Webhooks", "description": "Webhook configuration" },
    { "name": "Workflows", "description": "Automated workflow configuration" },
    { "name": "Analytics", "description": "Form analytics and view data" }
  ]
}