Hedge Binding API

openapi: 3.2.0
info:
  title: Hedgespecialty Com Binding API
  version: '1.0'
  description: 'Operations tagged Binding 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: Binding
paths:
  /broker/submissions/{submission_id}/partner-bind-links:
    post:
      tags:
      - Binding
      operationId: createPartnerBindLink
      summary: Mint a one-time bind link (partner integrations only)
      description: 'For an API partner acting for your brokerage (a token carrying the

        partner claim, with `broker_submit`) on a submission that partner

        created. Returns a one-time Hedge portal sign-in URL for

        `producer_email` that opens this quote: `landing` is `bind` (the bind

        checklist), `quote` (terms still incomplete, or the quote binds on

        the carrier''s own portal) or `status` (the lane is binding or bound).

        The URL expires after about 120 seconds and works once. It is a

        credential: redirect the signed-in user to it immediately and never

        store, email or log it. The first redemption makes the partner''s

        file a normal Hedge file.


        `producer_email` must be an active portal user of your brokerage, or

        a producer on file with your brokerage (Hedge then creates their

        portal account; no email is sent). `return_url` must be https on an

        origin Hedge approved for the partner; the portal offers it as the

        way back. Any other caller, or a submission the partner did not

        create, gets 404.'
      parameters:
      - in: path
        name: submission_id
        required: true
        schema:
          type: string
          format: uuid
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - quote_id
              - producer_email
              - return_url
              - consent
              additionalProperties: false
              properties:
                quote_id:
                  type: string
                  format: uuid
                  description: A quote from GET .../quotes.
                producer_email:
                  type: string
                  maxLength: 255
                return_url:
                  type: string
                  maxLength: 2048
                consent:
                  type: object
                  required:
                  - statement_version
                  - accepted_at
                  additionalProperties: false
                  properties:
                    statement_version:
                      type: string
                      maxLength: 128
                    accepted_at:
                      type: string
                      format: date-time
                      description: Must carry a UTC offset.
      responses:
        '201':
          description: 'The link (the response carries `Cache-Control: no-store`)'
          content:
            application/json:
              schema:
                type: object
                properties:
                  url:
                    type: string
                  expires_at:
                    type: string
                    format: date-time
                  landing:
                    type: string
                    enum:
                    - bind
                    - quote
                    - status
        '403':
          description: Missing broker_submit scope
          or a staff impersonation session: null
        '404':
          description: Not a partner token
          not the partner's submission: null
          or not your brokerage's: null
        '409':
          description: '`quote_not_available`, `quote_expired`, `quote_not_bindable` (with `reason`), `brokerage_portal_disabled` or `producer_email_conflict`'
        '422':
          description: '`return_url_not_allowed`, `producer_not_provisioned`, or a body validation error'
        '429':
          description: Rate limited (60 links a minute per partner
          10 an hour per quote): null
        '503':
          description: '`proposal_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/submissions/{submission_id}/bind-requests:
    post:
      tags:
      - Binding
      operationId: createBindRequest
      summary: Request to bind a released quote
      description: 'The broker''s bind authority over the API. Drafts a bind request for

        the chosen quote — the same request the Hedge portal''s bind wizard

        creates — allocating one response slot per pre-bind contingency the

        carrier listed. Idempotent per carrier lane: re-posting for the same

        quote returns the existing draft (and records any new

        `attest_assumptions`).


        **Assumptions.** Instant quotes are obtained on recorded assumptions

        (values Hedge defaulted on the carrier application because the file

        did not state them). They print on the signable application, so the

        retail agent must confirm them before the order reaches the carrier.

        This is the only bind check, and it is surfaced here rather than

        holding a submitted request silently: while any remain unconfirmed

        the response is **409 `assumptions_unconfirmed`** listing them; the

        draft is kept. Re-POST with `attest_assumptions: true` (or the keys

        the agent confirmed) to record the confirmation and receive the

        draft. Nothing is sent to a carrier by this call.


        **Money.** Lanes whose bind collects card payment in the portal

        (direct-bill carriers) cannot be submitted over the API; `submit`

        answers 422 with the reason. Requires the `broker_submit` scope;

        machine credentials must name `producer_email`.'
      parameters:
      - in: path
        name: submission_id
        required: true
        schema:
          type: string
          format: uuid
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BindRequestCreate'
      responses:
        '201':
          description: The bind request draft (or the existing draft for this quote)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BindRequestRead'
        '403':
          description: broker_submit scope required
        '404':
          description: Submission or quote not found (or not your brokerage's)
        '409':
          description: Standing assumptions are not yet confirmed; the draft exists
          content:
            application/json:
              schema:
                type: object
                properties:
                  detail:
                    $ref: '#/components/schemas/BindAssumptionsUnconfirmed'
        '422':
          description: Not bindable (an indication, a superseded quote, a lane already binding), or producer_email missing/unknown for a machine credential
    get:
      tags:
      - Binding
      operationId: listBindRequests
      summary: List this submission's bind requests
      description: Newest first, every status. Each row carries the same shape as the detail read.
      parameters:
      - in: path
        name: submission_id
        required: true
        schema:
          type: string
          format: uuid
      responses:
        '200':
          description: Bind requests
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/BindRequestRead'
        '404':
          description: Submission 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}/bind-requests/{bind_request_id}:
    get:
      tags:
      - Binding
      operationId: getBindRequest
      summary: Get one bind request
      description: 'Current status, the assumptions still unconfirmed, each pre-bind

        contingency with your response state and (while drafted) its upload

        path, and plain `next_steps`. Poll this, or the submission events

        feed / webhooks for `bound`.'
      parameters:
      - in: path
        name: submission_id
        required: true
        schema:
          type: string
          format: uuid
      - in: path
        name: bind_request_id
        required: true
        schema:
          type: string
          format: uuid
      responses:
        '200':
          description: Bind request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BindRequestRead'
        '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}/bind-requests/{bind_request_id}/contingencies/{contingency_id}/document:
    post:
      tags:
      - Binding
      operationId: uploadBindContingencyDocument
      summary: Attach a document to a pre-bind contingency
      description: 'Multipart upload (`file`, a PDF up to 15 MB; optional `notes`, max

        2000 characters; `producer_email` for machine credentials). Each

        call appends a file to that item — the same upload the portal

        wizard performs — and marks the response satisfied. Accepted only

        while the request is `drafted` (409 otherwise) and only for a

        contingency on the request''s selected quote (404 otherwise). PDF is

        the only accepted type (415 for anything else); uploads count toward

        your brokerage''s daily document-upload limit (429 when reached).

        Signature-collected items (`signed_form` with e-sign) can also be

        satisfied by uploading the signed PDF here.'
      parameters:
      - in: path
        name: submission_id
        required: true
        schema:
          type: string
          format: uuid
      - in: path
        name: bind_request_id
        required: true
        schema:
          type: string
          format: uuid
      - in: path
        name: contingency_id
        required: true
        schema:
          type: string
          format: uuid
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              required:
              - file
              properties:
                file:
                  type: string
                  format: binary
                  description: A PDF
                  at most 15 MB: null
                notes:
                  type: string
                  maxLength: 2000
                producer_email:
                  type: string
      responses:
        '200':
          description: The refreshed bind request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BindRequestRead'
        '400':
          description: Empty file
        '403':
          description: broker_submit scope required
        '404':
          description: Submission
          bind request: null
          or contingency not found (a contingency not on the request's selected quote is not found): null
        '409':
          description: The bind request is no longer drafted
        '413':
          description: File exceeds the 15 MB limit
        '415':
          description: Not a PDF
        '422':
          description: Wrong document for a carrier-signed application
          or producer_email missing/unknown for a machine credential: null
        '429':
          description: Daily document-upload limit reached
    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}/bind-requests/{bind_request_id}/submit:
    post:
      tags:
      - Binding
      operationId: submitBindRequest
      summary: Submit the bind request to Hedge for placement
      description: 'The wizard''s own submit, same validation: the request moves from

        `drafted` to `submitted` and Hedge places the bind with the carrier

        (your brokerage''s approval settings decide whether a Hedge reviewer

        looks first). While assumptions remain unconfirmed this answers 409

        `assumptions_unconfirmed` — pass `attest_assumptions` in the body to

        confirm and submit in one call. Surplus-lines placements need a

        diligent search on file (422 says so); direct-bill card-payment lanes

        are portal-only (422). A `bound` event follows on the events feed

        and webhooks once the carrier binds.'
      parameters:
      - in: path
        name: submission_id
        required: true
        schema:
          type: string
          format: uuid
      - in: path
        name: bind_request_id
        required: true
        schema:
          type: string
          format: uuid
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BindRequestSubmit'
      responses:
        '200':
          description: The submitted bind request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BindRequestRead'
        '403':
          description: broker_submit scope required
        '404':
          description: Submission or bind request not found
        '409':
          description: Assumptions unconfirmed, already submitted, or the selected quote changed
          content:
            application/json:
              schema:
                type: object
                properties:
                  detail:
                    oneOf:
                    - $ref: '#/components/schemas/BindAssumptionsUnconfirmed'
                    - type: string
        '422':
          description: Not yet submittable (effective date out of range
          diligent search owed: null
          required declaration or card payment missing: null
          producer_email missing): null
    servers:
    - url: https://api.hedgespecialty.com/api/v1
      description: Production
    - url: https://staging-api.hedgespecialty.com/api/v1
      description: Staging sandbox
components:
  schemas:
    BindRequestRead:
      type: object
      required:
      - bind_request_id
      - submission_id
      - status
      - status_label
      - requested_at
      - unconfirmed_assumptions
      - contingencies
      - next_steps
      properties:
        bind_request_id:
          type: string
          format: uuid
        submission_id:
          type: string
          format: uuid
        status:
          type: string
          enum:
          - drafted
          - submitted
          - sent
          - binder_received
          - bound
          - bind_failed
          - cancelled
          - declined
          - expired
          description: '`drafted`: checklist open (upload documents, confirm assumptions,

            then submit). `submitted`/`sent`: Hedge is placing the bind with

            the carrier. `binder_received`: the carrier confirmed the bind;

            coverage is bound and its policy documents are pending.

            `bound`: the policy is issued (it appears under GET

            /broker/policies and a `bound` event is emitted). `bind_failed`:

            Hedge is reviewing.

            '
        status_label:
          type: string
        quote_id:
          type: string
          format: uuid
          nullable: true
        payment_option:
          type: string
          nullable: true
        requested_at:
          type: string
          format: date-time
        requested_by:
          type: string
          nullable: true
          description: The producing broker the request is attributed to.
        effective_date:
          type: string
          format: date
          nullable: true
        policy_id:
          type: string
          format: uuid
          nullable: true
        unconfirmed_assumptions:
          type: array
          items:
            $ref: '#/components/schemas/BindAssumption'
          description: Standing assumptions the retail agent still has to confirm. Non-empty means create/submit will answer 409 `assumptions_unconfirmed` until attested.
        contingencies:
          type: array
          items:
            $ref: '#/components/schemas/BindContingency'
        next_steps:
          type: array
          items:
            type: string
          description: Plain-language actions for the current state, in order.
    BindRequestCreate:
      type: object
      required:
      - quote_id
      properties:
        quote_id:
          type: string
          format: uuid
          description: 'The released firm quote to bind: the `quote_id` shown on this

            submission''s rail lanes / markets rows. Indications cannot be

            bound (422).

            '
        payment_option:
          type: string
          enum:
          - in_full
          - monthly
          default: in_full
          description: The payment plan requested on the bind order.
        attest_assumptions:
          description: '`false` (default) confirms nothing. `true` confirms EVERY

            standing assumption on the quote''s carrier application (the set

            `unconfirmed_assumptions` lists). A list of keys confirms only

            those keys; keys matching no standing assumption are ignored,

            never invented. Send `true`/keys only after the retail agent has

            reviewed each statement: the confirmation is recorded on the bind

            request''s timeline under the producing broker (the same record

            the QB writes for a broker''s written confirmation). It is a

            recorded consent, not a hold, and it is the ONLY bind check.

            '
          oneOf:
          - type: boolean
          - type: array
            items:
              type: string
          default: false
        producer_email:
          type: string
          description: REQUIRED with a machine credential; the active portal user this bind is attributed to (`requested_by`). Ignored for per-user tokens.
    BindAssumptionsUnconfirmed:
      type: object
      description: '409 body from create/submit. The bind request exists as a draft

        (`bind_request_id`); re-POST the create (idempotent for the same

        quote) or POST submit with `attest_assumptions` to confirm.

        '
      required:
      - code
      - message
      - bind_request_id
      - assumptions
      properties:
        code:
          type: string
          const: assumptions_unconfirmed
        message:
          type: string
        bind_request_id:
          type: string
          format: uuid
        assumptions:
          type: array
          items:
            $ref: '#/components/schemas/BindAssumption'
    BindRequestSubmit:
      type: object
      properties:
        attest_assumptions:
          description: Same semantics as on create; lets the caller confirm at submit time.
          oneOf:
          - type: boolean
          - type: array
            items:
              type: string
          default: false
        producer_email:
          type: string
          description: REQUIRED with a machine credential.
    BindContingency:
      type: object
      description: One pre-bind item the carrier needs, with your response state.
      required:
      - id
      - kind
      - label
      - status
      - required
      properties:
        id:
          type: string
          format: uuid
        kind:
          type: string
          enum:
          - question
          - signed_form
          - loss_runs
          - file_upload
        label:
          type: string
          description: The carrier's wording of the item.
        status:
          type: string
          enum:
          - pending
          - satisfied
          - waived
        required:
          type: boolean
        upload_path:
          type: string
          nullable: true
          description: While the request is `drafted`, the path to POST a PDF for this item (multipart `file`); null afterwards.
        esign_status:
          type: string
          nullable: true
          description: Envelope state of a signature request started for this item through the Hedge portal wizard (e.g. sent, completed, queued_for_review); null when none.
    BindAssumption:
      type: object
      description: 'One assumption Hedge made to obtain the quote (a value it defaulted

        on the carrier application because the file did not state it) that

        the retail agent has not yet confirmed. `key` is what

        `attest_assumptions` lists; `label` is the plain-language statement;

        `value` is the exact value asserted to the carrier (absent when the

        entry records none).

        '
      required:
      - key
      - label
      properties:
        key:
          type: string
        label:
          type: string
        value:
          description: The asserted value
          any JSON type; may be absent.: null
  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