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

# Upload an invoice file

> Attach a file to an invoice – such as the PDF invoice document. Uploaded files are associated with the invoice and stored securely by Tilta.

You can attach files to an invoice to provide supporting documentation for the financing transaction. The most common use case is uploading the actual PDF invoice document so that Tilta and the buyer have access to the official commercial invoice associated with the financed amount. Files are stored securely and linked to the invoice record. Uploads use `multipart/form-data` encoding – include both the file binary and a document type classification in the same request.

<Note>
  Do not set a `Content-Type: application/json` header on this request. The `multipart/form-data` content type is set
  automatically by your HTTP client when you include `--form` fields.
</Note>

<Tip>
  Upload the PDF invoice document immediately after creating the invoice to ensure Tilta has the supporting documentation
  available for the full financing lifecycle, including any potential disputes or audits.
</Tip>


## OpenAPI

````yaml POST /v1/invoices/{external_id}/files
openapi: 3.0.0
info:
  version: 0.0.1
  title: Tilta API
  description: Tilta API documentation
servers:
  - url: https://api.tilta.io
    description: Tilta Production API
  - url: https://api.tilta-sandbox.io
    description: Tilta Sandbox API
security: []
paths:
  /v1/invoices/{external_id}/files:
    post:
      tags:
        - Invoices
      summary: Upload a file for an invoice
      description: Upload a File for an invoice.
      parameters:
        - schema:
            type: string
            maxLength: 100
            pattern: ^[a-zA-Z0-9-_]+$
            description: Unique identifier of an invoice.
          required: true
          name: external_id
          in: path
      requestBody:
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                files:
                  anyOf:
                    - type: object
                      properties:
                        type:
                          type: string
                          enum:
                            - file
                        fieldname:
                          type: string
                        filename:
                          type: string
                        encoding:
                          type: string
                        mimetype:
                          type: string
                        file:
                          nullable: true
                        fields:
                          nullable: true
                        toBuffer:
                          nullable: true
                      required:
                        - type
                        - fieldname
                        - filename
                        - encoding
                        - mimetype
                    - type: array
                      items:
                        type: object
                        properties:
                          type:
                            type: string
                            enum:
                              - file
                          fieldname:
                            type: string
                          filename:
                            type: string
                          encoding:
                            type: string
                          mimetype:
                            type: string
                          file:
                            nullable: true
                          fields:
                            nullable: true
                          toBuffer:
                            nullable: true
                        required:
                          - type
                          - fieldname
                          - filename
                          - encoding
                          - mimetype
                      minItems: 1
                types:
                  anyOf:
                    - type: object
                      properties:
                        type:
                          type: string
                          enum:
                            - field
                        value:
                          type: string
                          enum:
                            - INVOICE
                            - CREDIT_NOTE
                            - PERFORMANCE_PROOF
                            - CONTRACT
                            - OTHER
                          description: The type of the file being uploaded.
                        fieldname:
                          type: string
                        mimetype:
                          type: string
                        encoding:
                          type: string
                        fieldnameTruncated:
                          type: boolean
                        valueTruncated:
                          type: boolean
                        fields:
                          nullable: true
                      required:
                        - type
                        - value
                        - fieldname
                        - mimetype
                        - encoding
                        - fieldnameTruncated
                        - valueTruncated
                    - type: array
                      items:
                        type: object
                        properties:
                          type:
                            type: string
                            enum:
                              - field
                          value:
                            type: string
                            enum:
                              - INVOICE
                              - CREDIT_NOTE
                              - PERFORMANCE_PROOF
                              - CONTRACT
                              - OTHER
                            description: The type of the file being uploaded.
                          fieldname:
                            type: string
                          mimetype:
                            type: string
                          encoding:
                            type: string
                          fieldnameTruncated:
                            type: boolean
                          valueTruncated:
                            type: boolean
                          fields:
                            nullable: true
                        required:
                          - type
                          - value
                          - fieldname
                          - mimetype
                          - encoding
                          - fieldnameTruncated
                          - valueTruncated
                      minItems: 1
              required:
                - files
                - types
      responses:
        '201':
          description: ''
          content:
            application/json:
              schema:
                type: string
        '400':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/badRequestSchema'
        '401':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/unauthorizedRequestSchema'
        '409':
          description: ''
          content:
            application/json:
              schema: {}
      security:
        - bearerAuth: []
components:
  schemas:
    badRequestSchema:
      type: object
      properties:
        code:
          type: string
          description: Error code
          example: BAD_REQUEST
        error:
          type: string
          description: Error message for debugging purposes
          example: Request validation failed. 1 issue found.
        issues:
          type: array
          items:
            type: object
            properties:
              code:
                type: string
                description: Issue code
                example: INVALID_TYPE
              path:
                type: string
                description: Issue path starting with body, params, querystring, or headers
                example: body.registered_at
              message:
                type: string
                description: Issue message for debugging purposes
                example: Invalid type
            required:
              - code
              - path
              - message
          description: List of issues
          example:
            - code: INVALID_TYPE
              path: body.registered_at
              message: Invalid type
      required:
        - code
        - error
        - issues
      description: Bad Request, see error message for details.
      example:
        code: BAD_REQUEST
        error: Request validation failed. 1 issue found.
        issues:
          - code: INVALID_TYPE
            path: body.registered_at
            message: Invalid type
    unauthorizedRequestSchema:
      type: object
      properties:
        error:
          type: string
          description: Error details.
          example: Unauthorized
        code:
          type: string
          description: Error code.
          example: UNAUTHORIZED
      required:
        - error
        - code
      description: Unauthorized Request.
      example:
        error: Unauthorized
        code: UNAUTHORIZED
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: Your Tilta API key, sent as `Bearer <key>`.

````