Requirements

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/hedgespecialty-com/json-schema/hedgespecialty-com-requirements-schema.json",
  "title": "Requirements",
  "description": "The live \"what's still needed\" view.",
  "x-generated": "2026-10-29",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/hedgespecialty-com-openapi.yml#/components/schemas/Requirements",
  "type": "object",
  "properties": {
    "submission_id": {
      "type": "string",
      "format": "uuid"
    },
    "insured_name": {
      "type": "string"
    },
    "lines": {
      "type": "array",
      "items": {
        "type": "string"
      }
    },
    "effective_date": {
      "type": "string",
      "format": "date"
    },
    "state": {
      "type": "string"
    },
    "forms": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "Application forms Hedge prepares for this risk (ACORD baseline + recommended carrier supplements)."
    },
    "marketing_status": {
      "type": "string",
      "enum": [
        "not_started",
        "matching",
        "matched",
        "no_markets_matched"
      ],
      "description": "Where the asynchronous marketing pipeline is. Matching runs for\na few minutes after `finalize`, so an empty `markets` list means\n\"still matching\" when this is `matching`; not \"no appetite\".\n"
    },
    "marketing_hint": {
      "type": [
        "string",
        "null"
      ],
      "description": "Human-readable next step for the current marketing_status."
    },
    "form_fill_active": {
      "type": "boolean",
      "description": "A live form-fill session owns the form set."
    },
    "markets": {
      "type": "array",
      "description": "Per-market readiness (deterministic, no model on this read).",
      "items": {
        "type": "object",
        "properties": {
          "market_name": {
            "type": "string"
          },
          "ready": {
            "type": "boolean"
          },
          "needs_from_you": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Items only you can supply."
          },
          "hedge_obtains": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Items Hedge fetches itself; informational."
          },
          "lane_id": {
            "type": [
              "string",
              "null"
            ],
            "format": "uuid",
            "description": "The market lane this row belongs to (same id as rail.lanes[].submission_market_id)."
          },
          "program": {
            "type": [
              "string",
              "null"
            ]
          },
          "program_category": {
            "$ref": "#/$defs/ProgramCategory"
          },
          "category_label": {
            "type": [
              "string",
              "null"
            ]
          },
          "broker_label": {
            "allOf": [
              {
                "$ref": "#/$defs/ProgramCategory"
              }
            ],
            "description": "The broker label from the program's authority: specialty when a carrier underwriter reviews every file (any channel); instant_quote for a binding API program; binding for a binding portal or email program. program_category is the route."
          }
        }
      }
    },
    "carrier_api_sessions": {
      "type": "array",
      "description": "Instant-quote (carrier API) sessions and their open question gaps.",
      "items": {
        "type": "object",
        "properties": {
          "session_id": {
            "type": "string",
            "format": "uuid"
          },
          "carrier_slug": {
            "type": "string"
          },
          "program": {
            "type": "string"
          },
          "status": {
            "type": "string"
          },
          "outcome": {
            "type": [
              "string",
              "null"
            ]
          },
          "completion_pct": {
            "type": "number"
          },
          "missing_questions": {
            "type": "array",
            "items": {
              "type": "object"
            }
          },
          "has_quote": {
            "type": "boolean"
          }
        }
      }
    },
    "documents_on_file": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "kind": {
            "type": "string"
          },
          "kind_label": {
            "type": "string"
          },
          "display_name": {
            "type": "string"
          }
        }
      }
    },
    "assessment": {
      "nullable": true,
      "allOf": [
        {
          "$ref": "#/$defs/RequirementsAssessment"
        }
      ],
      "description": "The canonical per-program requirements assessment (null if that section failed to build)."
    },
    "rail": {
      "nullable": true,
      "allOf": [
        {
          "$ref": "#/$defs/MarketRail"
        }
      ],
      "description": "The per-lane market rail, the same block the broker portal shows (null if that section failed to build)."
    }
  },
  "$defs": {
    "AssessedRequirement": {
      "type": "object",
      "properties": {
        "key": {
          "type": [
            "string",
            "null"
          ]
        },
        "label": {
          "type": "string"
        },
        "severity": {
          "type": "string",
          "description": "hard or preferred"
        },
        "resolution": {
          "type": "string",
          "description": "broker (you supply), auto (Hedge fetches) or internal"
        },
        "repr": {
          "type": "string",
          "description": "structured, free_text, form or file"
        },
        "form_key": {
          "type": [
            "string",
            "null"
          ]
        },
        "due_stage": {
          "type": "string",
          "description": "quote or bind"
        },
        "satisfied": {
          "type": [
            "boolean",
            "null"
          ]
        },
        "blocks_submission": {
          "type": [
            "boolean",
            "null"
          ]
        }
      }
    },
    "MarketRail": {
      "type": "object",
      "properties": {
        "generated_at": {
          "type": "string",
          "format": "date-time"
        },
        "lanes": {
          "type": "array",
          "items": {
            "$ref": "#/$defs/RailLane"
          }
        },
        "quote_history": {
          "type": "array",
          "description": "Expired or invalidated quotes, for context.",
          "items": {
            "type": "object",
            "properties": {
              "history_key": {
                "type": "string"
              },
              "market_name": {
                "type": "string"
              },
              "program": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "outcome": {
                "type": "string",
                "enum": [
                  "expired",
                  "invalid"
                ]
              },
              "observed_at": {
                "type": "string",
                "format": "date-time"
              },
              "next_step": {
                "type": [
                  "string",
                  "null"
                ]
              }
            }
          }
        },
        "quote_history_unavailable": {
          "type": "boolean"
        },
        "online_in_progress_lines": {
          "type": "array",
          "items": {
            "type": "string"
          },
          "description": "Lines (canonical slugs) online markets are still quoting without\nhaving been named to you yet. Show one unnamed \"Online quotes in\nprogress\" line each; the markets appear in `lanes` once they\nquote, decline or ask you something.\n"
        },
        "no_market_lines": {
          "type": "array",
          "items": {
            "type": "string"
          },
          "description": "Lines (canonical slugs) no market is working or shows; every market on them closed."
        }
      }
    },
    "ProgramCategory": {
      "type": "string",
      "enum": [
        "instant_quote",
        "binding",
        "specialty"
      ],
      "description": "The Hedge category of a market program, derived from how Hedge\nsubmits to it. `instant_quote` (\"Hedge Instant Quote\"): carrier API,\nHedge fills gaps with favorable assumptions and quotes in minutes;\nevery assumption is listed for the retail agent to confirm before\nbind. `binding` (\"Hedge Binding\"): carrier portal, Hedge quotes on\nyour behalf. `specialty` (\"Hedge Specialty\"): email to an\nunderwriter; completed ACORDs, program supplements and loss runs\nare needed and a human reads them, so Hedge does not assume.\n"
    },
    "RailLane": {
      "type": "object",
      "description": "One market lane on this submission, in the shape the broker portal renders.",
      "properties": {
        "submission_market_id": {
          "type": "string",
          "format": "uuid",
          "description": "The lane id used across this API (lane_id elsewhere)."
        },
        "market_id": {
          "type": [
            "string",
            "null"
          ],
          "format": "uuid"
        },
        "market_name": {
          "type": [
            "string",
            "null"
          ]
        },
        "program": {
          "type": [
            "string",
            "null"
          ]
        },
        "program_id": {
          "type": [
            "string",
            "null"
          ],
          "format": "uuid"
        },
        "program_category": {
          "$ref": "#/$defs/ProgramCategory"
        },
        "broker_label": {
          "$ref": "#/$defs/ProgramCategory"
        },
        "lines": {
          "type": "array",
          "items": {
            "type": "string"
          }
        },
        "status": {
          "type": "string"
        },
        "status_label": {
          "type": "string"
        },
        "status_detail": {
          "type": [
            "string",
            "null"
          ],
          "description": "A closed market's reason. Beside \"Declined\", the carrier's own words; beside \"Not a fit\", one fixed reason."
        },
        "submit_ready": {
          "type": "boolean"
        },
        "gapped": {
          "type": "boolean",
          "description": "Held for something only you can supply (see `unmet_labels`)."
        },
        "unmet_labels": {
          "type": "array",
          "items": {
            "type": "string"
          }
        },
        "quotes": {
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "quote_id": {
                "type": "string",
                "format": "uuid"
              },
              "premium_display": {
                "type": "string"
              },
              "total_cents": {
                "type": "integer"
              },
              "lines": {
                "type": "array",
                "items": {
                  "type": "string"
                }
              },
              "is_revision": {
                "type": [
                  "boolean",
                  "null"
                ]
              }
            }
          }
        },
        "source_offers": {
          "type": "array",
          "description": "Carrier-original quote or indication documents.",
          "items": {
            "type": "object",
            "properties": {
              "presentation_id": {
                "type": "string",
                "format": "uuid"
              },
              "kind": {
                "type": "string",
                "enum": [
                  "quote",
                  "indication"
                ]
              },
              "label": {
                "type": "string"
              },
              "document_url": {
                "type": "string"
              },
              "filename": {
                "type": [
                  "string",
                  "null"
                ]
              }
            }
          }
        },
        "bound": {
          "type": "boolean"
        },
        "chip": {
          "type": "string",
          "enum": [
            "bound",
            "quoted",
            "not_available",
            "needs_info",
            "in_progress"
          ]
        },
        "carrier_api_session_ids": {
          "type": [
            "array",
            "null"
          ],
          "items": {
            "type": "string",
            "format": "uuid"
          }
        }
      }
    },
    "RequirementsAssessment": {
      "type": "object",
      "description": "Every matched program with what it needs. `gapped` lists lanes an\nenforcing program is holding for a broker-supplied item;\n`submitted_or_ready` lists lanes that are ready or already sent.\nPrograms with `enforcement: report_only` list `unmet` items but\nare NOT held; never render them as waiting on you.\n",
      "properties": {
        "submission_id": {
          "type": "string",
          "format": "uuid"
        },
        "generated_at": {
          "type": "string",
          "format": "date-time"
        },
        "submitted_or_ready": {
          "type": "array",
          "items": {
            "type": "string",
            "format": "uuid"
          }
        },
        "gapped": {
          "type": "array",
          "items": {
            "type": "string",
            "format": "uuid"
          }
        },
        "programs": {
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "submission_market_id": {
                "type": "string",
                "format": "uuid"
              },
              "market_name": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "program_id": {
                "type": [
                  "string",
                  "null"
                ],
                "format": "uuid"
              },
              "program_display_name": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "channel": {
                "type": [
                  "string",
                  "null"
                ],
                "enum": [
                  "email",
                  "api",
                  "portal",
                  null
                ]
              },
              "program_category": {
                "$ref": "#/$defs/ProgramCategory"
              },
              "broker_label": {
                "$ref": "#/$defs/ProgramCategory"
              },
              "enforcement": {
                "type": "string",
                "enum": [
                  "enforce",
                  "report_only",
                  "none"
                ]
              },
              "submit_ready": {
                "type": "boolean"
              },
              "met": {
                "type": "array",
                "items": {
                  "$ref": "#/$defs/AssessedRequirement"
                }
              },
              "unmet": {
                "type": "array",
                "items": {
                  "$ref": "#/$defs/AssessedRequirement"
                }
              },
              "deferred": {
                "type": "array",
                "items": {
                  "$ref": "#/$defs/AssessedRequirement"
                }
              },
              "evaluated_at": {
                "type": "string",
                "format": "date-time"
              }
            }
          }
        }
      }
    }
  }
}