> ## Documentation Index
> Fetch the complete documentation index at: https://docs.herondata.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Upload PDF files for broker submission

> Upload one or more PDF files for a specified broker submission.
Authenticate by passing a broker API key in the `x-api-key` header. Generate keys via the `/api/broker_submissions/api_keys/generate` endpoint.




## OpenAPI

````yaml https://app.herondata.io/swagger post /api/broker_submissions/{submission_heron_id}/files
openapi: 3.0.0
info:
  contact:
    email: support@herondata.io
    name: Support
  title: Heron Data API
  version: '2021-07-19'
servers:
  - description: Production
    url: https://app.herondata.io
security:
  - ApiKeyAuth:
      - key_XXX
externalDocs:
  description: Read Tutorial
  url: https://docs.herondata.io/
paths:
  /api/broker_submissions/{submission_heron_id}/files:
    post:
      tags:
        - BrokerSubmissions
      summary: Upload PDF files for broker submission
      description: >
        Upload one or more PDF files for a specified broker submission.

        Authenticate by passing a broker API key in the `x-api-key` header.
        Generate keys via the `/api/broker_submissions/api_keys/generate`
        endpoint.
      parameters:
        - description: The unique identifier for the broker submission to upload files to
          in: path
          name: submission_heron_id
          required: true
          schema:
            example: sub_1a2b3c4d5e6f
            type: string
      requestBody:
        content:
          multipart/form-data:
            examples:
              multiple_files:
                summary: Upload multiple files
                value:
                  files:
                    - january.pdf
                    - february.pdf
                    - march.pdf
              single_file:
                summary: Upload single file
                value:
                  files:
                    - file_q4.pdf
              with_file_class:
                summary: Upload with explicit file class
                value:
                  file_class: iso_application_form
                  files:
                    - iso_app.pdf
              without_downstream_processing:
                summary: Upload without triggering downstream processing
                value:
                  downstream_processing: false
                  files:
                    - statement.pdf
            schema:
              properties:
                downstream_processing:
                  default: true
                  description: >
                    (Optional) Whether to trigger downstream processing
                    (classification, parsing, Flowmingo workflow start, etc.)
                    after the files are uploaded. Defaults to true to preserve
                    existing behaviour. Set to false to upload files without
                    triggering downstream processing — useful when uploading
                    multiple files in sequence and you only want the workflow to
                    start after the final upload.
                  example: true
                  type: boolean
                file_class:
                  description: >
                    (Optional) The type of document being uploaded. Applies to
                    all files in this request. If omitted, Heron's file
                    classifier will automatically determine the file type.
                    Common values: bank_statement, iso_application_form,
                    debt_summary, void_check, invoice, pnl_statement,
                    balance_sheet, tax_return.
                  example: bank_statement
                  type: string
                files:
                  description: Array of PDF files to upload.
                  items:
                    format: binary
                    type: string
                  maxItems: 12
                  minItems: 1
                  type: array
              required:
                - files
              type: object
        required: true
      responses:
        '201':
          content:
            application/json:
              schema:
                items:
                  properties:
                    file:
                      description: Name of the uploaded file
                      example: statement_q4.pdf
                      type: string
                    status:
                      description: Status of the file upload
                      enum:
                        - uploaded
                      example: uploaded
                      type: string
                  type: object
                type: array
          description: All files uploaded successfully
        '207':
          content:
            application/json:
              schema:
                items:
                  properties:
                    file:
                      description: Name of the file
                      example: statement.pdf
                      type: string
                    reason:
                      description: Error reason (only present when status is "error")
                      example: Duplicate file
                      type: string
                    status:
                      description: Status of the file upload
                      enum:
                        - uploaded
                        - error
                      example: uploaded
                      type: string
                  type: object
                type: array
          description: Partial success - some files uploaded, others failed
        '400':
          content:
            application/json:
              schema:
                items:
                  properties:
                    file:
                      description: Name of the file
                      example: invalid.pdf
                      type: string
                    reason:
                      description: Reason for failure
                      example: >-
                        File type application/msword not allowed. Allowed:
                        application/pdf
                      type: string
                    status:
                      description: Status of the file upload
                      enum:
                        - error
                      example: error
                      type: string
                  type: object
                type: array
          description: All files failed validation or upload, or no files attached
        '401':
          content:
            application/json:
              schema:
                properties:
                  description:
                    example: Unauthorized
                    type: string
                type: object
          description: Missing or invalid API key
        '404':
          content:
            application/json:
              schema:
                properties:
                  description:
                    example: Broker submission sub_1a2b3c4d5e6f not found
                    type: string
                type: object
          description: >-
            Broker submission not found, or does not belong to the authenticated
            broker
        '422':
          content:
            application/json:
              schema:
                properties:
                  description:
                    example: >-
                      Invalid file_class 'invalid_value'. Must be a valid file
                      class name.
                    type: string
                type: object
          description: >-
            Request payload failed validation (e.g. invalid file_class, file too
            large, wrong mime type, too few or too many files)
      security:
        - ApiKeyAuth: []
components:
  securitySchemes:
    ApiKeyAuth:
      in: header
      name: x-api-key
      type: apiKey

````