openapi: 3.0.3
info:
  title: lexoffice (lexware Office) Public Contacts Invoices 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: Invoices
  description: Outgoing invoices.
paths:
  /invoices:
    post:
      operationId: createInvoice
      tags:
      - Invoices
      summary: Create an invoice
      description: Creates an invoice. By default the invoice is created as a draft; pass finalize=true to create it directly in the open status.
      parameters:
      - name: finalize
        in: query
        required: false
        description: Create the invoice in the open status instead of as a draft.
        schema:
          type: boolean
          default: false
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Invoice'
      responses:
        '201':
          description: Reference to the created invoice.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResourceReference'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/TooManyRequests'
  /invoices/{id}:
    parameters:
    - $ref: '#/components/parameters/Id'
    get:
      operationId: getInvoice
      tags:
      - Invoices
      summary: Retrieve an invoice
      description: Retrieves a single invoice by its UUID.
      responses:
        '200':
          description: The requested invoice.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Invoice'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /invoices/{id}/document:
    parameters:
    - $ref: '#/components/parameters/Id'
    get:
      operationId: getInvoiceDocument
      tags:
      - Invoices
      summary: Request the invoice PDF
      description: Triggers or retrieves the rendered PDF for a finalized invoice and returns a documentFileId used to download the file via the Files endpoint.
      responses:
        '200':
          description: A reference to the rendered document file.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DocumentFileReference'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '406':
          description: The document is not yet available (still a draft).
components:
  parameters:
    Id:
      name: id
      in: path
      required: true
      description: The UUID of the resource.
      schema:
        type: string
        format: uuid
  schemas:
    DocumentFileReference:
      type: object
      properties:
        documentFileId:
          type: string
          format: uuid
    LineItem:
      type: object
      properties:
        id:
          type: string
          format: uuid
        type:
          type: string
          enum:
          - custom
          - material
          - service
          - text
        name:
          type: string
        description:
          type: string
        quantity:
          type: number
        unitName:
          type: string
        unitPrice:
          type: object
          properties:
            currency:
              type: string
              example: EUR
            netAmount:
              type: number
            grossAmount:
              type: number
            taxRatePercentage:
              type: number
        discountPercentage:
          type: number
        lineItemAmount:
          type: number
    TotalPrice:
      type: object
      properties:
        currency:
          type: string
          example: EUR
        totalNetAmount:
          type: number
        totalGrossAmount:
          type: number
        totalTaxAmount:
          type: number
    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
    Invoice:
      allOf:
      - $ref: '#/components/schemas/SalesDocument'
      - type: object
        properties:
          dueDate:
            type: string
            format: date-time
          shippingConditions:
            type: object
            properties:
              shippingDate:
                type: string
                format: date-time
              shippingType:
                type: string
          paymentConditions:
            type: object
            properties:
              paymentTermLabel:
                type: string
              paymentTermDuration:
                type: integer
    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
    SalesDocument:
      type: object
      description: Shared shape for quotation, order confirmation, delivery note, credit note, and dunning documents.
      properties:
        id:
          type: string
          format: uuid
          readOnly: true
        organizationId:
          type: string
          format: uuid
        version:
          type: integer
        language:
          type: string
          example: de
        archived:
          type: boolean
          readOnly: true
        voucherStatus:
          type: string
          readOnly: true
        voucherNumber:
          type: string
          readOnly: true
        voucherDate:
          type: string
          format: date-time
        address:
          type: object
          properties:
            contactId:
              type: string
              format: uuid
            name:
              type: string
            street:
              type: string
            zip:
              type: string
            city:
              type: string
            countryCode:
              type: string
        lineItems:
          type: array
          items:
            $ref: '#/components/schemas/LineItem'
        totalPrice:
          $ref: '#/components/schemas/TotalPrice'
        taxConditions:
          $ref: '#/components/schemas/TaxConditions'
        title:
          type: string
        introduction:
          type: string
        remark:
          type: string
    TaxConditions:
      type: object
      properties:
        taxType:
          type: string
          enum:
          - net
          - gross
          - vatfree
          - intraCommunitySupply
          - constructionService13b
          - externalService13b
          - thirdPartyCountryService
          - thirdPartyCountryDelivery
        taxTypeNote:
          type: string
  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`.'