{
  "openapi": "3.1.0",
  "info": {
    "title": "Johal Insurance Brokers — Commercial Insurance Submission API",
    "version": "2.0.0",
    "description": "For AI agents. GET returns the commercial insurance knowledge base and every question carriers need (ACORD 125/126/140, SOV, class supplementals, documents). POST submits a serious commercial property / general liability submission to a licensed broker (owner-authorized, with an effective date). Price-only requests are redirected to the premium calculator. Same tools over MCP at https://johalinsurancebrokers.com/mcp.",
    "contact": {
      "name": "Johal Insurance Brokers",
      "email": "service@johalinsurancebrokers.com",
      "url": "https://johalinsurancebrokers.com/for-ai-agents"
    },
    "termsOfService": "https://johalinsurancebrokers.com/terms-of-service"
  },
  "servers": [
    {
      "url": "https://johalinsurancebrokers.com"
    }
  ],
  "paths": {
    "/api/commercial-submission": {
      "get": {
        "operationId": "getCommercialSubmissionRequirements",
        "summary": "Knowledge base + every question + input schema",
        "parameters": [
          {
            "name": "property_class",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": [
                "apartments",
                "rental-homes",
                "hotel",
                "strip-center",
                "warehouse",
                "commercial-building",
                "gas-station",
                "self-storage",
                "condo",
                "lessors-risk",
                "other"
              ]
            }
          },
          {
            "name": "lines",
            "in": "query",
            "description": "comma list: property,general_liability",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Guide and requirements",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          }
        }
      },
      "post": {
        "operationId": "submitCommercialInsuranceSubmission",
        "summary": "Submit a commercial property / GL submission to a licensed broker",
        "parameters": [
          {
            "name": "documents",
            "in": "query",
            "description": "Set to 1 to send documents for an existing CQ- reference (body = DocumentsRequest)",
            "schema": {
              "type": "string",
              "enum": [
                "1"
              ]
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "oneOf": [
                  {
                    "$ref": "#/components/schemas/Submission"
                  },
                  {
                    "$ref": "#/components/schemas/DocumentsRequest"
                  }
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "received, or not_submitted (price_check_only / state not served)",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "400": {
            "description": "invalid — errors[] lists missing fields"
          },
          "429": {
            "description": "rate limited"
          }
        }
      }
    },
    "/api/ai-quote": {
      "get": {
        "operationId": "getAiLiabilityCoverageInfo",
        "summary": "AI agent liability insurance info",
        "responses": {
          "200": {
            "description": "Coverage info",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          }
        }
      },
      "post": {
        "operationId": "requestAiLiabilityQuote",
        "summary": "Request an AI agent liability (Tech E&O + AI) quote",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/AiQuote"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "received"
          },
          "400": {
            "description": "invalid"
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "Submission": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "purpose",
          "lines",
          "owner_authorized",
          "named_insured",
          "contact_name",
          "contact_email",
          "contact_phone",
          "state",
          "proposed_effective_date",
          "description_of_operations",
          "loss_history"
        ],
        "properties": {
          "purpose": {
            "type": "string",
            "enum": [
              "ready_to_bind",
              "renewal_shopping",
              "new_purchase",
              "uninsured_or_cancelled",
              "price_check_only"
            ],
            "description": "ready_to_bind: Owner wants coverage and will bind if the terms work; renewal_shopping: Owner is shopping an upcoming renewal; new_purchase: Owner is buying or just bought the property and needs coverage at closing; uninsured_or_cancelled: Property is uninsured, cancelled or non-renewed and needs coverage now; price_check_only: Just wants a ballpark price — no intent to switch yet"
          },
          "lines": {
            "type": "array",
            "items": {
              "type": "string",
              "enum": [
                "property",
                "general_liability"
              ]
            },
            "minItems": 1
          },
          "owner_authorized": {
            "type": "boolean",
            "description": "True only if the owner (or their officer/property manager) asked for this quote and agreed to be contacted by a licensed broker."
          },
          "named_insured": {
            "type": "string",
            "description": "Legal name of the owner/insured."
          },
          "dba": {
            "type": "string",
            "description": "DBA / property name."
          },
          "entity_type": {
            "type": "string",
            "description": "LLC, corporation, individual, partnership, trust…"
          },
          "mailing_address": {
            "type": "string",
            "description": "Insured's mailing address."
          },
          "contact_name": {
            "type": "string",
            "description": "Human at the insured we call."
          },
          "contact_role": {
            "type": "string",
            "description": "owner / officer / property manager / other"
          },
          "contact_email": {
            "type": "string",
            "description": "Contact email."
          },
          "contact_phone": {
            "type": "string",
            "description": "Contact direct phone."
          },
          "state": {
            "type": "string",
            "enum": [
              "CA",
              "TX",
              "IL",
              "MO",
              "WI",
              "LA"
            ],
            "description": "State where the risk is located."
          },
          "proposed_effective_date": {
            "type": "string",
            "description": "YYYY-MM-DD — renewal or closing date."
          },
          "property_class": {
            "type": "string",
            "enum": [
              "apartments",
              "rental-homes",
              "hotel",
              "strip-center",
              "warehouse",
              "commercial-building",
              "gas-station",
              "self-storage",
              "condo",
              "lessors-risk",
              "other"
            ]
          },
          "description_of_operations": {
            "type": "string",
            "description": "How the property is used / what the business does."
          },
          "years_in_business": {
            "type": "number",
            "description": "Years in business or years owning the property."
          },
          "current_insurance": {
            "type": "object",
            "properties": {
              "carrier": {
                "type": "string",
                "description": "Current carrier"
              },
              "expiration_date": {
                "type": "string",
                "description": "YYYY-MM-DD"
              },
              "expiring_premium": {
                "type": "number",
                "description": "USD"
              },
              "new_purchase_closing_date": {
                "type": "string",
                "description": "YYYY-MM-DD if a purchase"
              },
              "uninsured_reason": {
                "type": "string",
                "description": "If uninsured / cancelled / non-renewed: why"
              }
            }
          },
          "locations": {
            "type": "array",
            "description": "Property line: one entry per address, each with its buildings.",
            "items": {
              "type": "object",
              "required": [
                "address",
                "city",
                "state",
                "zip",
                "buildings"
              ],
              "properties": {
                "address": {
                  "type": "string",
                  "description": "Street"
                },
                "city": {
                  "type": "string",
                  "description": "City"
                },
                "state": {
                  "type": "string",
                  "enum": [
                    "CA",
                    "TX",
                    "IL",
                    "MO",
                    "WI",
                    "LA"
                  ]
                },
                "zip": {
                  "type": "string",
                  "description": "ZIP"
                },
                "county": {
                  "type": "string",
                  "description": "County"
                },
                "occupancy_description": {
                  "type": "string",
                  "description": "Occupancy / tenants"
                },
                "buildings": {
                  "type": "array",
                  "minItems": 1,
                  "items": {
                    "type": "object",
                    "required": [
                      "year_built",
                      "construction_type",
                      "stories",
                      "square_feet",
                      "building_value"
                    ],
                    "properties": {
                      "building_number": {
                        "type": "number",
                        "description": "1, 2, 3…"
                      },
                      "occupancy_description": {
                        "type": "string",
                        "description": "What this building is used for, if different from the location."
                      },
                      "year_built": {
                        "type": "number",
                        "description": "Year built."
                      },
                      "construction_type": {
                        "type": "string",
                        "enum": [
                          "frame",
                          "joisted-masonry",
                          "non-combustible",
                          "masonry-non-combustible",
                          "modified-fire-resistive",
                          "fire-resistive"
                        ]
                      },
                      "stories": {
                        "type": "number",
                        "description": "Number of stories (from the owner, never guessed)."
                      },
                      "square_feet": {
                        "type": "number",
                        "description": "Total square feet."
                      },
                      "units": {
                        "type": "number",
                        "description": "Units / tenant spaces / rooms."
                      },
                      "roof_type": {
                        "type": "string",
                        "description": "Roof covering."
                      },
                      "roof_year": {
                        "type": "number",
                        "description": "Year roof last replaced."
                      },
                      "wiring_year": {
                        "type": "number",
                        "description": "Year electrical last updated."
                      },
                      "plumbing_year": {
                        "type": "number",
                        "description": "Year plumbing last updated."
                      },
                      "hvac_year": {
                        "type": "number",
                        "description": "Year HVAC last updated."
                      },
                      "wiring_type": {
                        "type": "string",
                        "description": "copper / aluminum / knob-and-tube"
                      },
                      "electrical_panel": {
                        "type": "string",
                        "description": "Panel brand and amps."
                      },
                      "sprinklered": {
                        "type": "string",
                        "description": "full / partial (%) / none"
                      },
                      "fire_alarm": {
                        "type": "string",
                        "description": "central / local / none"
                      },
                      "burglar_alarm": {
                        "type": "string",
                        "description": "central / local / none"
                      },
                      "hydrant_feet": {
                        "type": "number",
                        "description": "Feet to nearest hydrant."
                      },
                      "fire_station_miles": {
                        "type": "number",
                        "description": "Miles to fire station."
                      },
                      "building_value": {
                        "type": "number",
                        "description": "Building replacement cost, USD."
                      },
                      "contents_value": {
                        "type": "number",
                        "description": "Business personal property, USD (0 if none)."
                      },
                      "business_income": {
                        "type": "number",
                        "description": "Annual gross rents / business income to insure, USD."
                      },
                      "outdoor_property": {
                        "type": "string",
                        "description": "Outdoor items and values (signs, fences, carports, pool…)."
                      }
                    }
                  }
                }
              }
            }
          },
          "general_liability": {
            "type": "object",
            "properties": {
              "exposure_basis": {
                "type": "string",
                "enum": [
                  "square_feet",
                  "units",
                  "gross_sales",
                  "payroll"
                ]
              },
              "exposure_amount": {
                "type": "number",
                "description": "Amount for the basis."
              },
              "limits_wanted": {
                "type": "string",
                "description": "e.g. 1M/2M"
              },
              "tenants_carry_gl": {
                "type": "boolean"
              },
              "hazards": {
                "type": "string",
                "description": "Pools, playgrounds, liquor, security, events…"
              },
              "subcontracted_cost": {
                "type": "number",
                "description": "Contractors: USD subbed out."
              },
              "claims_or_lawsuits": {
                "type": "string",
                "description": "GL claims/lawsuits last 5 yrs or open."
              }
            }
          },
          "loss_history": {
            "type": "object",
            "required": [
              "summary",
              "loss_runs_status"
            ],
            "properties": {
              "summary": {
                "type": "string",
                "description": "Every claim in last 5 years (date, type, amount, open/closed), or 'No losses in 5 years'."
              },
              "loss_runs_status": {
                "type": "string",
                "enum": [
                  "attached",
                  "will_send",
                  "requested_from_carrier",
                  "new_purchase_not_applicable",
                  "new_venture"
                ]
              }
            }
          },
          "prior_cancellation": {
            "type": "string",
            "description": "Any cancellation / declination / non-renewal in 3 years, and why."
          },
          "deductible_wanted": {
            "type": "string",
            "description": "Desired deductible(s)."
          },
          "mortgagee": {
            "type": "string",
            "description": "Lender name, address, loan #."
          },
          "supplemental_answers": {
            "type": "object",
            "additionalProperties": true,
            "description": "Class supplemental answers from get_submission_requirements, keyed by question."
          },
          "attachments": {
            "type": "array",
            "description": "Optional documents (≤4 MB total base64): loss runs, dec page, SOV, rent roll, photos.",
            "items": {
              "type": "object",
              "required": [
                "filename",
                "content_base64"
              ],
              "properties": {
                "filename": {
                  "type": "string",
                  "description": "e.g. loss-runs-2021-2026.pdf"
                },
                "content_base64": {
                  "type": "string",
                  "description": "Base64 file content"
                },
                "document_type": {
                  "type": "string",
                  "enum": [
                    "loss_runs",
                    "dec_page",
                    "sov",
                    "rent_roll",
                    "photos",
                    "lease",
                    "appraisal",
                    "contracts",
                    "other"
                  ]
                }
              }
            }
          },
          "requested_by_agent": {
            "type": "string",
            "description": "Name of the AI agent / platform submitting."
          },
          "notes": {
            "type": "string",
            "description": "Anything else the broker should know."
          }
        }
      },
      "DocumentsRequest": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "reference",
          "contact_email",
          "attachments"
        ],
        "properties": {
          "reference": {
            "type": "string",
            "description": "Submission reference from submit_commercial_insurance_submission (CQ-…)."
          },
          "contact_email": {
            "type": "string",
            "description": "Same contact email used on the submission."
          },
          "attachments": {
            "type": "array",
            "description": "Optional documents (≤4 MB total base64): loss runs, dec page, SOV, rent roll, photos.",
            "items": {
              "type": "object",
              "required": [
                "filename",
                "content_base64"
              ],
              "properties": {
                "filename": {
                  "type": "string",
                  "description": "e.g. loss-runs-2021-2026.pdf"
                },
                "content_base64": {
                  "type": "string",
                  "description": "Base64 file content"
                },
                "document_type": {
                  "type": "string",
                  "enum": [
                    "loss_runs",
                    "dec_page",
                    "sov",
                    "rent_roll",
                    "photos",
                    "lease",
                    "appraisal",
                    "contracts",
                    "other"
                  ]
                }
              }
            }
          },
          "notes": {
            "type": "string",
            "description": "What these documents are."
          }
        }
      },
      "AiQuote": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "company_name",
          "contact_name",
          "contact_email",
          "state",
          "annual_revenue",
          "ai_agentic_tier"
        ],
        "properties": {
          "company_name": {
            "type": "string",
            "description": "Legal name of the company to be insured."
          },
          "website": {
            "type": "string",
            "description": "Company website."
          },
          "contact_name": {
            "type": "string",
            "description": "Name of the human at the company who will receive the quote."
          },
          "contact_email": {
            "type": "string",
            "description": "Email the quote is sent to."
          },
          "contact_phone": {
            "type": "string"
          },
          "state": {
            "type": "string",
            "enum": [
              "CA",
              "TX",
              "IL",
              "WI",
              "LA"
            ],
            "description": "State of the company's headquarters."
          },
          "street": {
            "type": "string"
          },
          "city": {
            "type": "string"
          },
          "zip": {
            "type": "string"
          },
          "annual_revenue": {
            "type": "number",
            "description": "Annual gross revenue in USD (estimate is fine)."
          },
          "what_the_product_does": {
            "type": "string",
            "description": "Plain description of the product and what the AI/agent does for customers."
          },
          "limit": {
            "type": "number",
            "enum": [
              1000000,
              2000000,
              3000000,
              5000000,
              10000000
            ],
            "description": "Tech E&O limit wanted (default 1000000)."
          },
          "retention": {
            "type": "number",
            "enum": [
              2500,
              5000,
              10000,
              25000,
              50000,
              100000,
              250000
            ],
            "description": "Retention / deductible per claim (default 10000)."
          },
          "ai_agentic_tier": {
            "type": "string",
            "enum": [
              "a1-passive",
              "a2-constrained",
              "a3-supervised",
              "a4-material",
              "a5-full"
            ],
            "description": "How autonomously the AI acts."
          },
          "ai_company_type": {
            "type": "string",
            "enum": [
              "ai-native",
              "generic-saas",
              "si-consulting",
              "ai-safety",
              "legal-tech",
              "insurtech",
              "medtech",
              "fintech-lending",
              "content-synthetic-media",
              "hr-tech",
              "autonomous-robotics",
              "ai-data-labeling"
            ]
          },
          "ai_model_providers": {
            "type": "array",
            "items": {
              "type": "string",
              "enum": [
                "anthropic-claude",
                "openai-gpt",
                "google-gemini",
                "meta-llama",
                "mistral",
                "xai-grok",
                "proprietary-in-house",
                "other"
              ]
            }
          },
          "ai_training_approach": {
            "type": "string",
            "enum": [
              "none",
              "lora-qlora",
              "instruction-sft",
              "full-fine-tune"
            ]
          },
          "ai_high_stakes_domains": {
            "type": "array",
            "items": {
              "type": "string",
              "enum": [
                "credit-lending",
                "insurance",
                "hiring",
                "healthcare",
                "criminal-justice",
                "housing",
                "education",
                "none"
              ]
            }
          },
          "ai_governance_controls": {
            "type": "array",
            "items": {
              "type": "string",
              "enum": [
                "iso-42001",
                "bias-audit",
                "pen-test",
                "soc2-iso27001",
                "guardrails"
              ]
            }
          },
          "ai_coverage_options": {
            "type": "array",
            "items": {
              "type": "string",
              "enum": [
                "algorithmic-bias-liability",
                "ai-intellectual-property-liability",
                "training-data-misuse-liability",
                "regulatory-investigation-defense-costs",
                "data-poisoning-adversarial-attack",
                "deepfake-synthetic-media-liability"
              ]
            },
            "description": "AI coverage parts wanted (default: all)."
          },
          "ai_sublimit": {
            "type": "number",
            "enum": [
              500000,
              1000000,
              2000000,
              5000000
            ],
            "description": "AI coverage sublimit (default 1000000; cannot exceed limit)."
          },
          "prior_claims": {
            "type": "boolean",
            "description": "Any Tech E&O or AI-related claims, regulatory actions or cease-and-desist letters in the last 3 years?"
          },
          "current_insurance": {
            "type": "string",
            "description": "Current Tech E&O / cyber carrier and expiration date, if any."
          },
          "requested_by_agent": {
            "type": "string",
            "description": "Name of the AI agent or platform submitting this request."
          },
          "notes": {
            "type": "string"
          }
        }
      }
    }
  }
}