openapi: 3.0.3
info:
  title: lexoffice (lexware Office) Public Contacts Files API
  description: Public REST API for lexoffice, the German cloud accounting and invoicing SaaS from Lexware (Haufe Group), rebranded to "lexware Office" in 2025. The API lets developers push and pull business data - contacts, invoices, quotations, order confirmations, delivery notes, credit notes, dunnings, bookkeeping vouchers, files, payments, and profile metadata - and subscribe to webhooks through event subscriptions. All requests are authenticated with a Bearer API key generated by the account owner at https://app.lexware.de/addons/public-api. The API is rate limited to 2 requests per second per client (HTTP 429 on exceed). The API gateway moved from api.lexoffice.io to api.lexware.io on 26 May 2025; the legacy host remained available through December 2025. This document is a representative, hand-authored subset grounded in the public documentation at https://developers.lexware.io/docs/ - it is not the vendor's own machine-readable specification.
  version: '1.0'
  contact:
    name: lexware Office Developers
    url: https://developers.lexware.io/docs/
  license:
    name: Proprietary
    url: https://www.lexware.de/
servers:
- url: https://api.lexware.io/v1
  description: Lexware API gateway (current)
- url: https://api.lexoffice.io/v1
  description: Legacy lexoffice API gateway (retired end of 2025)
security:
- bearerAuth: []
tags:
- name: Files
  description: File upload and download for voucher receipts.
paths:
  /files:
    post:
      operationId: uploadFile
      tags:
      - Files
      summary: Upload a file
      description: Uploads a receipt file (PDF, JPG, or PNG) to be attached to a voucher. Sent as multipart/form-data with a file part and a type of "voucher".
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                file:
                  type: string
                  format: binary
                type:
                  type: string
                  example: voucher
      responses:
        '200':
          description: Reference to the uploaded file.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResourceReference'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '406':
          description: Unsupported media type or file too large.
  /files/{id}:
    parameters:
    - $ref: '#/components/parameters/Id'
    get:
      operationId: downloadFile
      tags:
      - Files
      summary: Download a file
      description: Downloads a previously uploaded or rendered file by its UUID.
      responses:
        '200':
          description: The binary file.
          content:
            application/pdf:
              schema:
                type: string
                format: binary
            image/jpeg:
              schema:
                type: string
                format: binary
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
components:
  parameters:
    Id:
      name: id
      in: path
      required: true
      description: The UUID of the resource.
      schema:
        type: string
        format: uuid
  schemas:
    Error:
      type: object
      properties:
        timestamp:
          type: string
          format: date-time
        status:
          type: integer
        error:
          type: string
        path:
          type: string
        message:
          type: string
        details:
          type: array
          items:
            type: object
            properties:
              violation:
                type: string
              field:
                type: string
              message:
                type: string
    ResourceReference:
      type: object
      properties:
        id:
          type: string
          format: uuid
        resourceUri:
          type: string
          format: uri
        createdDate:
          type: string
          format: date-time
        updatedDate:
          type: string
          format: date-time
        version:
          type: integer
  responses:
    Unauthorized:
      description: Missing or invalid Bearer API key.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    NotFound:
      description: The requested resource was not found.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: 'Bearer API key generated by the account owner at https://app.lexware.de/addons/public-api and passed as `Authorization: Bearer YOUR_API_KEY`.'