Hedge Programs API

openapi: 3.2.0
info:
  title: Hedgespecialty Com Programs API
  version: '1.0'
  description: 'Operations tagged Programs 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: Programs
paths:
  /broker/programs:
    get:
      tags:
      - Programs
      operationId: listPrograms
      summary: The carrier programs (products) your brokerage can quote through Hedge
      description: 'The same catalog as GET /broker/market-access, flattened to one row

        per program with its broker category. `instant_quote` programs are

        quoted live through a carrier API and expose an application question

        schema (below) that your own application builder can plug into;

        `binding` programs Hedge quotes for you; `specialty` programs need

        completed ACORDs, program requirements and loss runs. Filters

        combine (AND). Read scope is enough.'
      parameters:
      - in: query
        name: category
        schema:
          type: string
          enum:
          - instant_quote
          - binding
          - specialty
      - in: query
        name: lob
        schema:
          type: string
        description: Canonical line slug or common alias (gl
        wc): null
      - in: query
        name: state
        schema:
          type: string
          minLength: 2
          maxLength: 2
      responses:
        '200':
          description: Programs, instant-quote first, then by market and name
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Program'
        '422':
          description: Unknown category
    servers:
    - url: https://api.hedgespecialty.com/api/v1
      description: Production
    - url: https://staging-api.hedgespecialty.com/api/v1
      description: Staging sandbox
  /broker/programs/{program_id}/application-schema:
    get:
      tags:
      - Programs
      operationId: getProgramApplicationSchema
      summary: The application question schema for an instant-quote program
      description: 'Exactly the questions Hedge''s carrier integration asks for this

        program — the schema the carrier application is filed on — projected

        for your own application builder: sections of questions with stable

        keys, labels, types, options, help, and `depends_on` visibility

        dependencies. Collect answers against these keys, then save them to

        the submission''s application via the application-workspace

        checkpoint. Optional `lob`/`state` check that the program lists that

        line / state.


        Served from Hedge''s schema cache only — the schema Hedge''s own

        quoting already filed on; this read never calls the carrier. Until

        Hedge''s first quote with a program the response is 404

        `code: application_schema_unavailable` (the list endpoint''s

        `application_schema_available` tells you in advance). Programs Hedge

        quotes itself have no schema: 404 `code: no_application_schema`

        pointing at GET /broker/markets/{market_id}/requirements.


        `questions` (with `schema_version`) is the same application in the

        shared question shape: exactly the questions the Hedge broker

        workspace asks for this program, one flat list in order. `key` is

        the shared answer key: Hedge''s fact key where the program''s question

        means the same fact in the same form (so one answer can prefill

        every program that asks it), otherwise

        `program..`. `show_if` / `required_if` are the

        full condition rules, keyed by `key`. Pass `lob` for the coverage

        being quoted: programs whose questions depend on the products Hedge

        selects for a line (Blitz) resolve them from it. `schema_version`

        changes whenever `questions` change; cache per `schema_version`.'
      parameters:
      - in: path
        name: program_id
        required: true
        schema:
          type: string
          format: uuid
      - in: query
        name: lob
        schema:
          type: string
      - in: query
        name: state
        schema:
          type: string
          minLength: 2
          maxLength: 2
      responses:
        '200':
          description: The projected question schema and the program's shared questions
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/ProgramApplicationSchema'
                - type: object
                  required:
                  - schema_version
                  - questions
                  properties:
                    schema_version:
                      type: string
                      description: Content hash of `questions`.
                    questions:
                      type: array
                      items:
                        $ref: '#/components/schemas/SharedQuestion'
        '404':
          description: 'Program not visible to your brokerage or not available for the given line/state (plain detail); not an instant-quote program (`code: no_application_schema`); or no schema cached yet (`code: application_schema_unavailable`)'
    servers:
    - url: https://api.hedgespecialty.com/api/v1
      description: Production
    - url: https://staging-api.hedgespecialty.com/api/v1
      description: Staging sandbox
components:
  schemas:
    ProgramQuestion:
      type: object
      required:
      - key
      - label
      - type
      - required
      - repeatable
      properties:
        key:
          type: string
          description: Stable answer key; use it as the answer key in application checkpoints.
        label:
          type: string
        type:
          type: string
          description: Normalized field type (e.g. text, number, boolean, select, multiselect, date, group, collection).
        required:
          type: boolean
        options:
          type: array
          nullable: true
          items:
            type: object
            properties:
              value: {}
              label:
                type: string
        help:
          type: string
          nullable: true
        depends_on:
          type: array
          nullable: true
          items:
            type: string
          description: Keys of other questions whose answers decide whether this one applies.
        required_when:
          type: object
          nullable: true
          description: 'Conditional requiredness when declared: {field, op (equals|not_equals|in|not_in|truthy|falsy), value}.'
        one_of_group:
          type: string
          nullable: true
        repeatable:
          type: boolean
          description: True for collections (answer is a list of items shaped by `questions`).
        questions:
          type: array
          nullable: true
          items:
            $ref: '#/components/schemas/ProgramQuestion'
          description: Nested questions for group / collection items.
    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.'
    Program:
      type: object
      required:
      - program_id
      - market_id
      - market_name
      - name
      - lines
      - enabled
      - application_schema_available
      properties:
        program_id:
          type: string
          format: uuid
        market_id:
          type: string
          format: uuid
        market_name:
          type: string
        name:
          type: string
        program_category:
          type: string
          nullable: true
          enum:
          - instant_quote
          - binding
          - specialty
          description: '`instant_quote`: quoted live through a carrier API; your own

            application can plug in via the program''s application-schema.

            `binding`: Hedge quotes it for you. `specialty`: completed

            ACORDs, program requirements and loss runs are required.

            '
        category_label:
          type: string
          nullable: true
        broker_label:
          type: string
          nullable: true
          enum:
          - instant_quote
          - binding
          - specialty
          description: 'The broker label from the program''s authority. `specialty`: a

            carrier underwriter reviews every file (any channel); completed

            ACORDs, program requirements and loss runs are required.

            `instant_quote`: a binding program quoted live through a carrier

            API. `binding`: a binding program Hedge quotes through its portal

            or email. `program_category` is the route.

            '
        lines:
          type: array
          items:
            type: string
          description: Canonical line-of-business slugs.
        states:
          type: array
          nullable: true
          items:
            type: string
          description: 2-letter state codes where the program is available; null means no state restriction.
        description:
          type: string
          nullable: true
        enabled:
          type: boolean
          description: Your brokerage's own on/off preference (see GET /broker/market-access).
        application_schema_available:
          type: boolean
          description: True when Hedge holds a cached question schema for this program (filed after Hedge's first quote with it), so GET /broker/programs/{program_id}/application-schema will serve it.
    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'
    ProgramApplicationSchema:
      type: object
      required:
      - program_id
      - market_id
      - name
      - program_category
      - contract_version
      - schema_fingerprint
      - sections
      properties:
        program_id:
          type: string
          format: uuid
        market_id:
          type: string
          format: uuid
        name:
          type: string
        program_category:
          type: string
          const: instant_quote
        contract_version:
          type: string
          const: structured_v1
        schema_fingerprint:
          type: string
          description: Content hash of the served schema; changes when the carrier's questions change. Per-application fingerprints for checkpoints come from the application-workspace.
        title:
          type: string
          nullable: true
        description:
          type: string
          nullable: true
        sections:
          type: array
          items:
            type: object
            required:
            - key
            - label
            - questions
            properties:
              key:
                type: string
              label:
                type: string
              questions:
                type: array
                items:
                  $ref: '#/components/schemas/ProgramQuestion'
  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