Hedge Documents API

openapi: 3.2.0
info:
  title: Hedgespecialty Com Documents API
  version: '1.0'
  description: 'Operations tagged Documents 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: Documents
paths:
  /broker/submissions/{submission_id}/finalized-documents:
    get:
      tags:
      - Documents
      operationId: listSubmissionDocuments
      summary: List a submission's documents
      description: 'Finalized documents on file for one of your submissions: rendered

        ACORDs, supplements, your own uploads, received documents. Each row

        carries `id`, `source`, `source_label`, `display_name`, `size_bytes`,

        `content_type`, `created_at` and a `download_path` for the PDF route

        below. Proposal-surface documents (carrier quote PDFs, bind-wizard

        uploads) are excluded.'
      parameters:
      - in: path
        name: submission_id
        required: true
        schema:
          type: string
          format: uuid
      responses:
        '200':
          description: Document list (empty for a submission that is not yours)
    servers:
    - url: https://api.hedgespecialty.com/api/v1
      description: Production
    - url: https://staging-api.hedgespecialty.com/api/v1
      description: Staging sandbox
  /broker/finalized-documents/{document_id}/pdf:
    get:
      tags:
      - Documents
      operationId: downloadSubmissionDocument
      summary: Download a submission document PDF
      description: Streams the PDF, brokerage-scoped. Form fields stay editable; widget appearances are baked so filled values render in any viewer.
      parameters:
      - in: path
        name: document_id
        required: true
        schema:
          type: string
          format: uuid
      responses:
        '200':
          description: The PDF bytes
          content:
            application/pdf: {}
        '404':
          description: Not found (or not your brokerage's)
        '502':
          description: Stored document could not be retrieved
    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}/package:
    get:
      tags:
      - Documents
      operationId: getSubmissionPackage
      summary: Read a submission's package
      description: 'What you send your own markets for one of your submissions: its risk

        summary and the application documents to go with it.


        `summary` has `status` (`none` until one is written, then `ready`),

        `text`, `sections`, `generated_at` and `stale` (true once the file''s

        facts changed after it was written; a portal session regenerates it).

        The text is written for an underwriter from the file''s own facts and

        every answer given on it, and lists no documents: add the ones you

        send. `sections` is the same summary as titled sections in display

        order, each with `items` (`label`, null for a plain line, and a

        formatted `value`) and `in_copy`: the sections where it is false

        (answers that differ between applications, and what Hedge assumed to

        get a quote) are for you and are never in the text.


        `groups` lists the documents: `forms` (the current version of each

        form Hedge prepared), `prefilled` (your ready "Get a form" copies) and

        `documents` (what you uploaded or emailed). Each has `id`,

        `file_name`, `attachment_label`, `selected` (ticked by default) and,

        when it isn''t ticked, a `note` saying why: a fill Hedge''s checks

        doubt, another market''s quote or binder, a blank copy or a broker of

        record letter. Carrier quote PDFs, bind uploads and internal filing

        paperwork are never listed.'
      parameters:
      - in: path
        name: submission_id
        required: true
        schema:
          type: string
          format: uuid
      responses:
        '200':
          description: The package
        '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}/package/download:
    post:
      tags:
      - Documents
      operationId: downloadSubmissionPackage
      summary: Download a submission's package as a ZIP
      description: 'A ZIP of the risk summary PDF (listing the documents it goes with)

        and the stored originals of the chosen documents; fillable forms stay

        fillable. Send `document_ids` to choose exactly which documents (each

        must be one of the package''s), or omit it for the ticked set. Set

        `include_summary` to false to leave the summary out.'
      parameters:
      - in: path
        name: submission_id
        required: true
        schema:
          type: string
          format: uuid
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                document_ids:
                  type: array
                  items:
                    type: string
                    format: uuid
                  maxItems: 100
                include_summary:
                  type: boolean
                  default: true
      responses:
        '200':
          description: The package
          content:
            application/zip:
              schema:
                type: string
                format: binary
        '404':
          description: Not found (or not your brokerage's)
        '413':
          description: The chosen documents are too large for one download (over 200 MB)
        '422':
          description: A document id that isn't part of this package
          or nothing chosen: null
        '502':
          description: A stored document could not be retrieved; the message names it
    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}/source-offers/{presentation_id}/original:
    get:
      tags:
      - Documents
      operationId: downloadCarrierOriginalOffer
      summary: Download a carrier's original quote or indication document
      description: Streams the carrier-original PDF referenced by `rail.lanes[].source_offers[].presentation_id`, brokerage-scoped.
      parameters:
      - in: path
        name: submission_id
        required: true
        schema:
          type: string
          format: uuid
      - in: path
        name: presentation_id
        required: true
        schema:
          type: string
          format: uuid
      responses:
        '200':
          description: The PDF bytes
          content:
            application/pdf: {}
        '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
components:
  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