Hedge Appetite API

openapi: 3.2.0
info:
  title: Hedgespecialty Com Appetite API
  version: '1.0'
  description: 'Operations tagged Appetite across 2 of this provider''s published API definitions: hedge-openapi.json, hedgespecialty-com-openapi.yml. Each path carries the servers of the definition it was published in.'
servers:
- url: https://api.hedgespecialty.com/api/v1
  description: Production
- url: https://staging-api.hedgespecialty.com/api/v1
  description: Staging sandbox
security:
- brokerOAuth: []
tags:
- name: Appetite
paths:
  /broker/submissions/{submission_id}/appetite-preview:
    get:
      tags:
      - Appetite
      operationId: getSubmissionAppetitePreview
      summary: Markets Hedge expects to approach for a draft
      description: 'Deterministic preview (no model) of the in-appetite markets for a

        submission''s lines, classification and state, filtered by your

        brokerage''s market visibility. Informational; marketing never waits on it.'
      parameters:
      - in: path
        name: submission_id
        required: true
        schema:
          type: string
          format: uuid
      responses:
        '200':
          description: '{markets: [{market_id, name, program, program_category, lines: [...]}], excluded_market_ids: [...]}'
        '404':
          description: Not found (or not your brokerage's)
    servers:
    - url: https://api.hedgespecialty.com/api/v1
      description: Production
    - url: https://staging-api.hedgespecialty.com/api/v1
      description: Staging sandbox
  /broker/submissions/{submission_id}/market-exclusions:
    put:
      tags:
      - Appetite
      operationId: setSubmissionMarketExclusions
      summary: Replace the set of markets to skip for this submission
      description: 'Idempotent full replacement of the market ids Hedge must not

        approach for this submission. Live instant-quote sessions with an

        excluded market are withdrawn. Requires `broker_submit`.'
      parameters:
      - in: path
        name: submission_id
        required: true
        schema:
          type: string
          format: uuid
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - excluded_market_ids
              properties:
                excluded_market_ids:
                  type: array
                  items:
                    type: string
                    format: uuid
      responses:
        '200':
          description: 'What persisted: {excluded_market_ids, withdrawn_sessions}'
        '404':
          description: Not found (or not your brokerage's)
    servers:
    - url: https://api.hedgespecialty.com/api/v1
      description: Production
    - url: https://staging-api.hedgespecialty.com/api/v1
      description: Staging sandbox
  /broker/appetite:
    get:
      tags:
      - Appetite
      operationId: checkAppetite
      summary: Which markets have appetite for a class of business
      parameters:
      - in: query
        name: q
        required: true
        schema:
          type: string
        description: Risk description, e.g. roofing contractor
      - in: query
        name: state
        schema:
          type: string
      - in: query
        name: lob
        schema:
          type: string
      responses:
        '200':
          description: Ranked markets with lines and matched programs
        '429':
          description: Daily appetite-check limit reached
    servers:
    - url: https://api.hedgespecialty.com/api/v1
      description: Production
    - url: https://staging-api.hedgespecialty.com/api/v1
      description: Staging sandbox
  /broker/appetite/search:
    post:
      tags:
      - Appetite
      operationId: searchPlacements
      summary: Structured appetite search (query + lines + state)
      description: 'The portal''s placement search: a free-text risk description plus

        optional lines and state, returning ranked markets with matched

        programs and their Hedge category. Same daily limit as `GET /broker/appetite`.'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                query:
                  type: string
                  maxLength: 2000
                state:
                  type: string
                  minLength: 2
                  maxLength: 2
                lines:
                  type: array
                  maxItems: 30
                  items:
                    type: string
      responses:
        '200':
          description: Ranked markets with matched programs
        '429':
          description: Daily appetite-check limit reached
    servers:
    - url: https://api.hedgespecialty.com/api/v1
      description: Production
    - url: https://staging-api.hedgespecialty.com/api/v1
      description: Staging sandbox
  /broker/catalog/query:
    post:
      tags:
      - Appetite
      operationId: queryMarketCatalog
      summary: The programs Hedge would try for lines, state and NAICS
      description: 'Deterministic, read-only (no submission is created). Returns the

        programs Hedge attaches on line of business for the request, after

        your brokerage''s market, program and line settings and Hedge''s state

        footprint: connected carrier APIs (`channel: api`) and portals Hedge

        drives (`channel: portal`). Email and manual-portal markets are

        listed only with `all_channels: true` (`channel: email` and

        `channel: portal`), each with an `appetite` status. Programs that

        only ever return a non-binding indication are never listed. A

        listing is a potential route, not a quote; for API and portal

        programs the carrier''s own application answers appetite.


        Hedge sends ONE program per market, channel and line. Every eligible

        sibling is listed; exactly one per market, channel and line is the

        default (`default_lines`), and the others name it in

        `alternative_of`. Programs that cannot be tried are in `excluded`

        with reason codes: your own Markets settings

        (`broker_market_excluded`, `broker_program_excluded`,

        `broker_program_line_excluded`), the program''s lines and states

        (`unsupported_requested_line`, `requested_coverage_mismatch`,

        `package_companion_not_requested`, `program_state_excluded`,

        `market_state_excluded`, `exposure_state_excluded`), Hedge''s state footprint

        (`brokerage_state_unavailable`), the request''s facts

        (`program_class_excluded`, `below_program_revenue_floor`,

        `above_program_revenue_limit`), or `program_unavailable` when the

        program cannot be tried right now.'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CatalogQuery'
      responses:
        '200':
          description: Offered and excluded programs
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CatalogResult'
        '422':
          description: 'Invalid body, or `{code: unknown_line, value}` for a line Hedge does not recognize'
    servers:
    - url: https://api.hedgespecialty.com/api/v1
      description: Production
    - url: https://staging-api.hedgespecialty.com/api/v1
      description: Staging sandbox
  /broker/hedge-questions:
    post:
      tags:
      - Appetite
      operationId: getHedgeQuestions
      summary: The Hedge supplemental questions for a risk (no submission needed)
      description: 'Deterministic and read-only. Returns the curated core questions of

        the Hedge supplemental form(s) that apply to the risk, merged so a

        shared `key` is asked once. Forms resolve in this order, at most

        four: the Hedge forms the selected `program_ids` require, the class

        form for the NAICS (the most specific prefix), or for the business

        `description` when the NAICS names no class form, then the coverage

        form of each requested line (liquor,

        auto, cyber, workers'' comp and so on; the general GL and property

        forms only when no class form covers the line). A form Hedge asks

        about but does not send as a PDF (the general GL supplemental) is not

        in `forms`; its questions are. An empty `forms` and `sections` is a

        valid answer: send the note and documents only.


        Answer with `POST /broker/submissions/{submission_id}/answers`

        (`source: hedge_questions`).'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - lines
              additionalProperties: false
              properties:
                lines:
                  type: array
                  minItems: 1
                  maxItems: 10
                  items:
                    type: string
                  description: Canonical lines of business.
                state:
                  type: string
                  description: Two-letter US state.
                naics:
                  type: string
                  description: 2 to 6 digits.
                program_ids:
                  type: array
                  maxItems: 100
                  items:
                    type: string
                    format: uuid
                  description: The selected Hedge (portal and email) programs.
                description:
                  type: string
                  maxLength: 1000
                  description: 'Optional: the agency''s description of the business, which class keywords match (for example cannabis, which has no NAICS).'
      responses:
        '200':
          description: The resolved forms and their questions
          content:
            application/json:
              schema:
                type: object
                required:
                - version
                - forms
                - sections
                properties:
                  version:
                    type: string
                    description: Changes when the question sets change, e.g. `HEDGE_14@2026-09-28.1`; `none` when no form applies.
                  forms:
                    type: array
                    items:
                      type: object
                      required:
                      - form_key
                      - title
                      properties:
                        form_key:
                          type: string
                          description: The Hedge form's key, e.g. HEDGE_14_RESTAURANT_BAR_AND_TAVERN_SUPPLEMENTAL.
                        title:
                          type: string
                  sections:
                    type: array
                    items:
                      type: object
                      required:
                      - id
                      - title
                      - questions
                      properties:
                        id:
                          type: string
                        title:
                          type: string
                        questions:
                          type: array
                          items:
                            $ref: '#/components/schemas/SharedQuestion'
        '422':
          description: 'Invalid body, or `{code: unknown_line}` for a line Hedge does not write'
        '503':
          description: '`hedge_questions_unavailable`: try again shortly'
    servers:
    - url: https://api.hedgespecialty.com/api/v1
      description: Production
    - url: https://staging-api.hedgespecialty.com/api/v1
      description: Staging sandbox
  /broker/appetite/guide:
    get:
      tags:
      - Appetite
      operationId: downloadAppetiteGuide
      summary: Download the Hedge Appetite & Markets Guide (PDF)
      responses:
        '200':
          description: The PDF bytes
          content:
            application/pdf: {}
    servers:
    - url: https://api.hedgespecialty.com/api/v1
      description: Production
    - url: https://staging-api.hedgespecialty.com/api/v1
      description: Staging sandbox
components:
  schemas:
    CatalogResult:
      type: object
      required:
      - catalog_version
      - generated_at
      - scope
      - programs
      - excluded
      properties:
        catalog_version:
          type: string
        generated_at:
          type: string
          format: date-time
        scope:
          type: object
          properties:
            lines:
              type: array
              items:
                type: string
            state:
              type: string
            exposure_states:
              type: array
              items:
                type: string
            naics:
              type: string
              nullable: true
            brokerage_scoped:
              type: boolean
            all_channels:
              type: boolean
        programs:
          type: array
          items:
            type: object
            properties:
              program_id:
                type: string
                format: uuid
              program_name:
                type: string
              market:
                type: object
                properties:
                  id:
                    type: string
                    format: uuid
                  slug:
                    type: string
                    nullable: true
                  display_name:
                    type: string
                  logo_url:
                    type: string
                    nullable: true
              issuing_company:
                type: object
                nullable: true
                properties:
                  legal_name:
                    type: string
                    nullable: true
                  naic:
                    type: string
                    nullable: true
                  admitted:
                    type: boolean
                    nullable: true
                  am_best_rating:
                    type: string
                    nullable: true
              channel:
                type: string
                enum:
                - api
                - portal
                - email
                description: '`email` only with `all_channels`. `portal` covers the portals Hedge drives and, with `all_channels`, manual portals.'
              group:
                type: string
                enum:
                - instant
                - hedge
                description: '`instant` for `api`; `hedge` for `portal` and `email`.'
              route_label:
                type: string
                enum:
                - Instant quote
                - Hedge Binding
                - Hedge Specialty
                description: Small-print route name for `api`, `portal` and `email` respectively.
              appetite:
                $ref: '#/components/schemas/CatalogAppetite'
              lines:
                type: array
                items:
                  type: string
              default_selected:
                type: boolean
              default_lines:
                type: array
                items:
                  type: string
                description: 'The lines this program is the default for. Pre-select each

                  default program with exactly these lines (one program per

                  market, channel and line). With `all_channels`, `hedge` rows

                  are pre-selected only when `fit` and among Hedge''s top picks

                  for the line (at most 8 per line, ranked by Hedge''s market

                  results); `instant` rows keep one default per market and line.

                  '
              alternative_of:
                type: string
                format: uuid
                nullable: true
                description: The sibling Hedge sends instead at the same market, channel and line; null for that primary program, pre-selected or not.
              speed:
                $ref: '#/components/schemas/SpeedHint'
              fit:
                type: string
                enum:
                - line_match
              warnings:
                type: array
                items:
                  type: string
              bind_path:
                type: string
                enum:
                - hedge_portal
        excluded:
          type: array
          items:
            type: object
            properties:
              program_id:
                type: string
                format: uuid
              program_name:
                type: string
              market:
                type: object
                properties:
                  id:
                    type: string
                    format: uuid
                  display_name:
                    type: string
              channel:
                type: string
                enum:
                - api
                - portal
                - email
              group:
                type: string
                enum:
                - instant
                - hedge
              route_label:
                type: string
                enum:
                - Instant quote
                - Hedge Binding
                - Hedge Specialty
              appetite:
                $ref: '#/components/schemas/CatalogAppetite'
              lines:
                type: array
                items:
                  type: string
              reasons:
                type: array
                items:
                  type: string
                example:
                - broker_program_excluded
    SpeedHint:
      type: object
      description: A channel-level expectation (`basis` is `channel_default`), never a per-program promise.
      required:
      - hint
      - label
      - basis
      properties:
        hint:
          type: string
          enum:
          - minutes
          - within_day
          - underwriter_review
        label:
          type: string
          example: Usually within minutes
        basis:
          type: string
          enum:
          - channel_default
    SharedQuestion:
      type: object
      required:
      - id
      - key
      - label
      - help
      - type
      - options
      - required
      - show_if
      - section
      - assumed_default
      - prefill_from
      properties:
        id:
          type: string
          description: The program's own answer path, stable within the set (an object's parts are `<object>.<part>`).
        key:
          type: string
          description: 'Shared answer key: Hedge''s fact key when the question means that fact in the same form, else `program.<program_slug>.<id>`.'
        label:
          type: string
        help:
          type: string
          nullable: true
        type:
          type: string
          enum:
          - text
          - textarea
          - number
          - currency
          - percent
          - integer
          - boolean
          - select
          - multiselect
          - date
          - state
          - address
          - list
          description: '`list`: the answer is a JSON array; rows shaped by `item_questions`, or plain text values when `item_questions` is absent.'
        options:
          type: array
          description: Choices for select / multiselect (empty otherwise). Send `value` unchanged; it may be a string, number or boolean.
          items:
            type: object
            required:
            - value
            - label
            properties:
              value: {}
              label:
                type: string
        required:
          type: boolean
          description: Required whenever the question is shown.
        show_if:
          type: array
          items:
            $ref: '#/components/schemas/SharedQuestionCondition'
        required_if:
          type: array
          items:
            $ref: '#/components/schemas/SharedQuestionCondition'
          description: When present, the question is required only while these conditions hold.
        one_of_group:
          type: string
          description: An answer to any question in the same group satisfies the group.
        section:
          type: string
          nullable: true
        assumed_default:
          nullable: true
          description: The answer Hedge would assume when unanswered, when one is fixed in advance; null otherwise (Hedge then decides from the file at quote time).
        prefill_from:
          type: string
          nullable: true
        item_questions:
          type: array
          items:
            $ref: '#/components/schemas/SharedQuestion'
          description: 'For a `list`: each row''s questions. Keys are `<list key>.<id>`; a row condition on a sibling uses the sibling''s key.'
    CatalogAppetite:
      type: object
      required:
      - status
      properties:
        status:
          type: string
          enum:
          - fit
          - review
          - excluded
          description: '`fit`: Hedge would send it (API and portal programs on line of

            business; email programs whose published appetite matches the

            NAICS class). `review`: passes every line, state, class and

            brokerage check, and Hedge reviews appetite before sending (the

            usual email case). `excluded`: a check fails (rows in `excluded`

            only).

            '
        reason:
          type: string
          nullable: true
          description: Plain-English reason to show when present.
    SharedQuestionCondition:
      type: object
      required:
      - key
      - op
      - value
      description: 'One condition on another question''s answer, found by that

        question''s `key`. Conditions in a list are ANDed. Semantics: `eq`

        and `in` compare type and value exactly; `ne` / `not_in` are false

        for an unanswered question; `truthy` is true unless the answer is

        null, false, 0, "" or an empty list or object; `falsy` is exactly

        false, 0 or "" (an unanswered question is not falsy); `gt` /

        `gte` / `lt` / `lte` compare numbers; `exists` is whether the

        question is answered. `any_of` / `all_of` group `conditions` (then

        `key` is null). `any_item`: the answer is a list and one item must

        satisfy `op` / `value`. A condition whose `key` no question carries

        refers to a fact Hedge sets itself; treat it as unanswered.

        '
      properties:
        key:
          type: string
          nullable: true
        op:
          type: string
          enum:
          - eq
          - ne
          - in
          - not_in
          - truthy
          - falsy
          - gt
          - gte
          - lt
          - lte
          - exists
          - any_of
          - all_of
        value:
          description: Comparison value (JSON)
          null for truthy / falsy / groups.: null
        any_item:
          type: boolean
        reference:
          type: object
          description: A keyed-row lookup Hedge evaluates natively.
        conditions:
          type: array
          items:
            $ref: '#/components/schemas/SharedQuestionCondition'
    CatalogQuery:
      type: object
      additionalProperties: false
      required:
      - lines
      - state
      properties:
        lines:
          type: array
          minItems: 1
          maxItems: 10
          items:
            type: string
            example: commercial_general_liability
          description: Hedge line slugs; `businessowners` expands to general liability plus property. Unknown values return 422 `unknown_line`.
        state:
          type: string
          minLength: 2
          maxLength: 2
          description: Primary risk state.
        exposure_states:
          type: array
          maxItems: 60
          items:
            type: string
          description: Every location state; each must pass the market and program state checks.
        naics:
          type: string
          pattern: ^\d{2,6}$
          nullable: true
        annual_revenue_cents:
          type: integer
          minimum: 0
          nullable: true
          description: Optional. Missing revenue is a warning (`revenue_unknown`)
          never an exclusion.: null
        effective_date:
          type: string
          format: date
          nullable: true
        all_channels:
          type: boolean
          default: false
          description: '`false` (default): connected carrier APIs and the portals Hedge

            drives, with one default per market, channel and line. `true`:

            every channel, adding manual-portal (`channel: portal`) and email

            (`channel: email`) programs, an `appetite` status on each row, and

            Hedge''s pre-checks for the `hedge` group (at most 8 per line).

            '
  securitySchemes:
    brokerOAuth:
      type: oauth2
      description: 'Broker access token. Scopes: `broker_mcp` (read), `broker_submit`

        (write). Per-user tokens come from the OAuth authorization-code +

        PKCE flow (`/oauth/authorize` → `/oauth/token`); machine tokens

        from `client_credentials`, using an API key created self-serve in

        the broker portal (Settings → API keys) or issued by Hedge ops.

        Access tokens live 60 minutes.

        '
      flows:
        authorizationCode:
          authorizationUrl: https://api.hedgespecialty.com/api/v1/oauth/authorize
          tokenUrl: https://api.hedgespecialty.com/api/v1/oauth/token
          scopes:
            broker_mcp: Read brokerage-scoped submissions, policies, payments, appetite, and requirements.
            broker_submit: Create submissions, answer Hedge's asks, and act on quotes for your brokerage.
        clientCredentials:
          tokenUrl: https://api.hedgespecialty.com/api/v1/oauth/token
          scopes:
            broker_mcp: Read brokerage-scoped submissions, policies, payments, appetite, and requirements.
            broker_submit: Create submissions, answer Hedge's asks, and act on quotes for your brokerage.
externalDocs:
  description: Hedge developer documentation
  url: https://docs.hedgespecialty.com
x-refined-from:
- hedge-openapi.json
- hedgespecialty-com-openapi.yml