openapi: 3.0.3
info:
  title: lexoffice (lexware Office) Public Contacts Vouchers 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: Vouchers
  description: Bookkeeping vouchers and the voucherlist search.
paths:
  /vouchers:
    post:
      operationId: createVoucher
      tags:
      - Vouchers
      summary: Create a bookkeeping voucher
      description: Creates a bookkeeping voucher (sales/purchase invoice or credit note) for preliminary accounting, with voucher items and an optional receipt file.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Voucher'
      responses:
        '200':
          description: Reference to the created voucher.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResourceReference'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/TooManyRequests'
  /vouchers/{id}:
    parameters:
    - $ref: '#/components/parameters/Id'
    get:
      operationId: getVoucher
      tags:
      - Vouchers
      summary: Retrieve a voucher
      responses:
        '200':
          description: The requested voucher.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Voucher'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
    put:
      operationId: updateVoucher
      tags:
      - Vouchers
      summary: Update a voucher
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Voucher'
      responses:
        '200':
          description: Reference to the updated voucher.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResourceReference'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
    delete:
      operationId: deleteVoucher
      tags:
      - Vouchers
      summary: Delete a voucher
      responses:
        '204':
          description: The voucher was deleted.
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /voucherlist:
    get:
      operationId: listVouchers
      tags:
      - Vouchers
      summary: Search the voucher list
      description: Returns a paged, filterable list of all voucher-type documents (invoices, credit notes, vouchers, etc.). The voucherType and voucherStatus filters are required.
      parameters:
      - name: voucherType
        in: query
        required: true
        description: Comma-separated voucher types (e.g. invoice, salesinvoice, purchaseinvoice, creditnote, any).
        schema:
          type: string
      - name: voucherStatus
        in: query
        required: true
        description: Comma-separated statuses (e.g. draft, open, paid, paidoff, voided, transferred, sepadebit, overdue, any).
        schema:
          type: string
      - name: archived
        in: query
        required: false
        schema:
          type: boolean
      - name: contactId
        in: query
        required: false
        schema:
          type: string
          format: uuid
      - $ref: '#/components/parameters/Page'
      - $ref: '#/components/parameters/Size'
      responses:
        '200':
          description: A page of voucherlist entries.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VoucherListPage'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/TooManyRequests'
components:
  parameters:
    Id:
      name: id
      in: path
      required: true
      description: The UUID of the resource.
      schema:
        type: string
        format: uuid
    Page:
      name: page
      in: query
      required: false
      description: Zero-based page index.
      schema:
        type: integer
        default: 0
    Size:
      name: size
      in: query
      required: false
      description: Page size (max 250 for most collections).
      schema:
        type: integer
        default: 25
  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
    VoucherListPage:
      type: object
      properties:
        content:
          type: array
          items:
            type: object
            properties:
              id:
                type: string
                format: uuid
              voucherType:
                type: string
              voucherStatus:
                type: string
              voucherNumber:
                type: string
              voucherDate:
                type: string
                format: date-time
              dueDate:
                type: string
                format: date-time
              contactName:
                type: string
              totalAmount:
                type: number
              openAmount:
                type: number
              currency:
                type: string
                example: EUR
              archived:
                type: boolean
        totalPages:
          type: integer
        totalElements:
          type: integer
        size:
          type: integer
        number:
          type: integer
    Voucher:
      type: object
      description: A bookkeeping voucher for preliminary accounting.
      properties:
        id:
          type: string
          format: uuid
          readOnly: true
        organizationId:
          type: string
          format: uuid
          readOnly: true
        type:
          type: string
          enum:
          - salesinvoice
          - salescreditnote
          - purchaseinvoice
          - purchasecreditnote
        voucherStatus:
          type: string
          enum:
          - open
          - paid
          - paidoff
          - voided
          - transferred
          - sepadebit
        voucherNumber:
          type: string
        voucherDate:
          type: string
          format: date-time
        shippingDate:
          type: string
          format: date-time
        dueDate:
          type: string
          format: date-time
        totalGrossAmount:
          type: number
        totalTaxAmount:
          type: number
        taxType:
          type: string
          enum:
          - net
          - gross
        useCollectiveContact:
          type: boolean
        contactId:
          type: string
          format: uuid
        remark:
          type: string
        voucherItems:
          type: array
          items:
            type: object
            properties:
              amount:
                type: number
              taxAmount:
                type: number
              taxRatePercent:
                type: number
              categoryId:
                type: string
                format: uuid
        files:
          type: array
          items:
            type: string
            format: uuid
        version:
          type: integer
  responses:
    Unauthorized:
      description: Missing or invalid Bearer API key.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    BadRequest:
      description: The request payload failed validation.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    NotFound:
      description: The requested resource was not found.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    TooManyRequests:
      description: Rate limit of 2 requests per second exceeded.
      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`.'