SubmissionCreate

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/hedgespecialty-com/json-schema/hedgespecialty-com-submission-create-schema.json",
  "title": "SubmissionCreate",
  "x-generated": "2026-10-29",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/hedgespecialty-com-openapi.yml#/components/schemas/SubmissionCreate",
  "type": "object",
  "required": [
    "applicant",
    "narrative"
  ],
  "properties": {
    "applicant": {
      "$ref": "#/$defs/Applicant"
    },
    "narrative": {
      "type": "string",
      "description": "Operations description of the risk, what the business does,\nsize, anything an underwriter should know. Required; appetite\nmatching depends on it.\n"
    },
    "lines_of_business": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "Canonical slugs (e.g. commercial_general_liability) or common aliases (gl, wc)."
    },
    "effective_date": {
      "type": "string",
      "format": "date"
    },
    "primary_state": {
      "type": "string",
      "minLength": 2,
      "maxLength": 2,
      "description": "Primary risk state, 2-letter US code (normalized to uppercase).\nWhen the applicant mailing address also carries a state the two\nmust agree: the request 422s on a conflict, with a message that\nsays exactly what to fix. Omit it to use the mailing address\nstate.\n"
    },
    "producer_email": {
      "type": "string",
      "description": "REQUIRED when authenticating with a machine credential, the active portal user this submission is attributed to."
    },
    "insured_id": {
      "type": "string",
      "format": "uuid",
      "description": "Optional id of an existing insured from GET /broker/insureds;\nlinks the new submission to that client's account (repeat\nbusiness, a new line for an existing client). Must belong to\nyour brokerage; an unknown or foreign id returns 404.\n"
    },
    "locations": {
      "type": "array",
      "maxItems": 250,
      "items": {
        "$ref": "#/$defs/Location"
      },
      "description": "Risk locations (ACORD 125 premises). Location numbers must be unique."
    },
    "requested_coverages": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "Explicit narrow coverage intent as canonical slugs (e.g.\nauto_physical_damage, motor_truck_cargo). Omit when unstated;\nan empty list means the broker explicitly selected none.\n"
    },
    "property_tiv_total": {
      "type": "integer",
      "minimum": 0,
      "description": "Total insured property value, whole dollars."
    },
    "auto_vehicle_count": {
      "type": "integer",
      "minimum": 0
    },
    "wc_total_annual_payroll": {
      "type": "integer",
      "minimum": 0,
      "description": "Total annual payroll, whole dollars."
    },
    "prior_carriers": {
      "type": "array",
      "items": {
        "$ref": "#/$defs/PriorCarrier"
      },
      "description": "Expiring or prior carriers per line; drives loss-run requests."
    },
    "line_target_premiums": {
      "type": "object",
      "additionalProperties": {
        "type": "integer",
        "minimum": 1
      },
      "description": "Broker-stated target annual premium per line slug, whole dollars. Non-positive values are dropped."
    },
    "structure_to_target": {
      "type": "boolean",
      "default": false,
      "description": "Ask Hedge to structure options (limits, deductibles) to hit the target premiums."
    },
    "hold": {
      "type": "boolean",
      "default": false,
      "description": "Defer the run. `false` (default) starts marketing as soon as the\ncreate commits — appetite match, clearance email to the\nproducer, lanes opened, instant-quote markets quoted. `true`\nholds the draft until `POST /broker/submissions/{id}/finalize`\nreleases it (attach documents and answer requirements first).\n"
    },
    "mode": {
      "type": "string",
      "enum": [
        "rater"
      ],
      "description": "Partner integrations only (an acting-as partner token; anyone\nelse gets 403). `rater` quotes exactly `partner_program_ids` and\nno other market. The file is always held until `finalize`, and\n`lines_of_business` and `primary_state` are required. A live\nsubmission for the same insured returns 409 `hedge_file_exists`\nwith its `submission_id`, except your own rater submissions\n(one per coverage) where no chosen program's market already\nquotes one of its lines and no carrier application is shared.\nDifferent markets may quote the same line on sibling\nsubmissions. When your own rater submission collides, the 409\nalso lists `programs`: each colliding `program_id`, its\n`reasons` (`market_line_on_live_file`,\n`carrier_application_on_live_file`, `lines_unknown`) and the\n`submission_ids` it collides with. Untick those and retry.\n"
    },
    "partner_program_ids": {
      "type": "array",
      "minItems": 1,
      "maxItems": 40,
      "uniqueItems": true,
      "items": {
        "type": "string",
        "format": "uuid"
      },
      "description": "With `mode: rater` only: the exact programs to quote (API,\nportal or email programs; a portal-robot program must be\nqualified on Hedge's executor), at most one per market and\nchannel for a requested line. Each refused program is named\nwith its reasons in a 422.\n"
    },
    "partner_reference": {
      "type": "string",
      "maxLength": 128,
      "description": "With `mode: rater` only, the partner's own id for this quote\nrequest; echoed on the file's start event.\n"
    }
  },
  "$defs": {
    "Address": {
      "type": "object",
      "description": "line1, city, state and zip are required together.",
      "required": [
        "line1",
        "city",
        "state",
        "zip"
      ],
      "properties": {
        "line1": {
          "type": "string"
        },
        "line2": {
          "type": "string"
        },
        "city": {
          "type": "string"
        },
        "county": {
          "type": "string"
        },
        "state": {
          "type": "string",
          "minLength": 2,
          "maxLength": 2
        },
        "zip": {
          "type": "string"
        },
        "zip4": {
          "type": "string"
        },
        "country": {
          "type": "string",
          "default": "US"
        }
      }
    },
    "Applicant": {
      "type": "object",
      "required": [
        "insured_name"
      ],
      "properties": {
        "insured_name": {
          "type": "string",
          "maxLength": 256
        },
        "dba_name": {
          "type": "string"
        },
        "entity_type": {
          "type": "string",
          "description": "Legal entity type, e.g. llc, corporation, sole_proprietor."
        },
        "fein_or_ssn": {
          "type": "string",
          "description": "FEIN, or SSN for a sole proprietor."
        },
        "nature_of_business": {
          "type": "string"
        },
        "date_business_started": {
          "type": "string",
          "format": "date"
        },
        "business_start_year": {
          "type": "integer",
          "description": "The year the business started, when the exact date is not known."
        },
        "business_phone": {
          "type": "string"
        },
        "business_email": {
          "type": "string"
        },
        "website": {
          "type": "string"
        },
        "contact_first_name": {
          "type": "string"
        },
        "contact_last_name": {
          "type": "string"
        },
        "contact_title": {
          "type": "string",
          "maxLength": 128
        },
        "contact_phone": {
          "type": "string"
        },
        "contact_email": {
          "type": "string",
          "description": "The producer's email. Strongly recommended: Hedge emails the\nclearance (every market being tried), any questions, and\nquotes here; the same thread an email broker gets.\n"
        },
        "naics": {
          "type": "string"
        },
        "sic": {
          "type": "string",
          "maxLength": 64
        },
        "gl_code": {
          "type": "string",
          "maxLength": 64
        },
        "mailing_address": {
          "$ref": "#/$defs/Address"
        }
      }
    },
    "Location": {
      "type": "object",
      "required": [
        "location_number",
        "address"
      ],
      "properties": {
        "location_number": {
          "type": "integer",
          "minimum": 1,
          "description": "Unique per submission."
        },
        "address": {
          "$ref": "#/$defs/Address"
        },
        "description_of_operations": {
          "type": "string",
          "maxLength": 10000
        },
        "employees_full_time": {
          "type": "integer",
          "minimum": 0
        },
        "employees_part_time": {
          "type": "integer",
          "minimum": 0
        },
        "annual_revenue_at_location": {
          "type": "number",
          "minimum": 0
        }
      }
    },
    "PriorCarrier": {
      "type": "object",
      "properties": {
        "coverage_category": {
          "type": "string",
          "description": "Canonical line slug or common alias."
        },
        "carrier_name": {
          "type": "string"
        },
        "policy_number": {
          "type": "string"
        },
        "effective_date": {
          "type": "string",
          "format": "date"
        },
        "expiration_date": {
          "type": "string",
          "format": "date"
        }
      }
    }
  }
}