Underwriting Submission

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "$id": "https://github.com/api-evangelist/underwriting-standards/blob/main/json-schema/underwriting-standards-submission-schema.json",
  "title": "Underwriting Submission",
  "description": "Schema for an insurance underwriting submission, representing the core data elements exchanged between brokers and carriers for risk assessment and policy binding.",
  "type": "object",
  "required": ["submissionId", "submittedAt", "risk", "requestedCoverages"],
  "properties": {
    "submissionId": {
      "type": "string",
      "description": "Unique identifier for the underwriting submission"
    },
    "externalReference": {
      "type": "string",
      "description": "Broker's or MGA's reference number for this submission"
    },
    "submittedAt": {
      "type": "string",
      "format": "date-time",
      "description": "ISO 8601 timestamp when the submission was created"
    },
    "status": {
      "type": "string",
      "description": "Current status of the submission",
      "enum": ["draft", "submitted", "under-review", "referred", "accepted", "declined", "quoted", "bound"]
    },
    "broker": {
      "$ref": "#/definitions/Party",
      "description": "The broker or agent submitting the risk"
    },
    "insured": {
      "$ref": "#/definitions/Party",
      "description": "The party seeking insurance coverage"
    },
    "risk": {
      "$ref": "#/definitions/Risk",
      "description": "The risk being underwritten"
    },
    "requestedCoverages": {
      "type": "array",
      "description": "Coverage types and limits being requested",
      "items": {
        "$ref": "#/definitions/Coverage"
      },
      "minItems": 1
    },
    "quotes": {
      "type": "array",
      "description": "Quotes generated by underwriters in response to this submission",
      "items": {
        "$ref": "#/definitions/Quote"
      }
    },
    "documents": {
      "type": "array",
      "description": "Supporting documents attached to the submission",
      "items": {
        "$ref": "#/definitions/Document"
      }
    },
    "notes": {
      "type": "string",
      "description": "Free-text notes from the broker"
    }
  },
  "definitions": {
    "Party": {
      "type": "object",
      "required": ["name"],
      "properties": {
        "partyId": {
          "type": "string",
          "description": "Unique identifier for the party"
        },
        "name": {
          "type": "string",
          "description": "Legal name of the party"
        },
        "type": {
          "type": "string",
          "description": "Party type",
          "enum": ["individual", "organization", "broker", "carrier", "mga", "reinsurer"]
        },
        "taxId": {
          "type": "string",
          "description": "Tax identification number (EIN, SSN, etc.)"
        },
        "address": {
          "$ref": "#/definitions/Address"
        },
        "contact": {
          "type": "object",
          "properties": {
            "email": {"type": "string", "format": "email"},
            "phone": {"type": "string"},
            "website": {"type": "string", "format": "uri"}
          }
        }
      }
    },
    "Address": {
      "type": "object",
      "properties": {
        "street1": {"type": "string"},
        "street2": {"type": "string"},
        "city": {"type": "string"},
        "state": {"type": "string"},
        "postalCode": {"type": "string"},
        "country": {"type": "string", "description": "ISO 3166-1 alpha-2 country code"}
      }
    },
    "Risk": {
      "type": "object",
      "required": ["lineOfBusiness"],
      "properties": {
        "lineOfBusiness": {
          "type": "string",
          "description": "Primary line of business for this risk",
          "enum": [
            "commercial-property",
            "general-liability",
            "professional-liability",
            "directors-and-officers",
            "cyber",
            "workers-compensation",
            "commercial-auto",
            "marine",
            "aviation",
            "life",
            "health",
            "disability",
            "other"
          ]
        },
        "naicsCode": {
          "type": "string",
          "description": "NAICS industry classification code for the insured's business"
        },
        "sicCode": {
          "type": "string",
          "description": "SIC industry classification code"
        },
        "description": {
          "type": "string",
          "description": "Description of the risk or business operations"
        },
        "annualRevenue": {
          "type": "number",
          "description": "Insured's annual revenue in USD"
        },
        "numberOfEmployees": {
          "type": "integer",
          "description": "Total number of employees"
        },
        "yearsInBusiness": {
          "type": "integer",
          "description": "Number of years the business has been operating"
        },
        "locations": {
          "type": "array",
          "description": "Physical locations associated with the risk",
          "items": {
            "$ref": "#/definitions/Address"
          }
        },
        "priorLosses": {
          "type": "array",
          "description": "Prior claims and loss history",
          "items": {
            "$ref": "#/definitions/LossRecord"
          }
        }
      }
    },
    "Coverage": {
      "type": "object",
      "required": ["coverageType"],
      "properties": {
        "coverageType": {
          "type": "string",
          "description": "Type of coverage requested"
        },
        "effectiveDate": {
          "type": "string",
          "format": "date",
          "description": "Requested policy effective date"
        },
        "expirationDate": {
          "type": "string",
          "format": "date",
          "description": "Requested policy expiration date"
        },
        "limitAmount": {
          "type": "number",
          "description": "Requested coverage limit in USD"
        },
        "deductibleAmount": {
          "type": "number",
          "description": "Requested deductible in USD"
        },
        "retentionAmount": {
          "type": "number",
          "description": "Self-insured retention amount in USD"
        }
      }
    },
    "Quote": {
      "type": "object",
      "properties": {
        "quoteId": {"type": "string"},
        "status": {
          "type": "string",
          "enum": ["draft", "issued", "accepted", "declined", "expired"]
        },
        "premium": {
          "type": "number",
          "description": "Annual premium in USD"
        },
        "issuedAt": {
          "type": "string",
          "format": "date-time"
        },
        "expiresAt": {
          "type": "string",
          "format": "date-time"
        },
        "conditions": {
          "type": "array",
          "description": "Underwriting conditions and requirements",
          "items": {"type": "string"}
        },
        "exclusions": {
          "type": "array",
          "description": "Coverage exclusions applied",
          "items": {"type": "string"}
        }
      }
    },
    "LossRecord": {
      "type": "object",
      "properties": {
        "dateOfLoss": {"type": "string", "format": "date"},
        "description": {"type": "string"},
        "claimAmount": {"type": "number"},
        "paidAmount": {"type": "number"},
        "status": {
          "type": "string",
          "enum": ["open", "closed", "reserved"]
        }
      }
    },
    "Document": {
      "type": "object",
      "properties": {
        "documentId": {"type": "string"},
        "name": {"type": "string"},
        "type": {
          "type": "string",
          "description": "Document type",
          "enum": ["acord-application", "loss-runs", "financial-statements", "inspection-report", "policy-dec-page", "other"]
        },
        "url": {"type": "string", "format": "uri"},
        "mimeType": {"type": "string"},
        "uploadedAt": {"type": "string", "format": "date-time"}
      }
    }
  }
}