openapi: 3.0.3
info:
  title: lexoffice (lexware Office) Public Contacts Event Subscriptions 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: Event Subscriptions
  description: Webhook subscriptions for change events.
paths:
  /event-subscriptions:
    get:
      operationId: listEventSubscriptions
      tags:
      - Event Subscriptions
      summary: List event subscriptions
      responses:
        '200':
          description: A list of event subscriptions.
          content:
            application/json:
              schema:
                type: object
                properties:
                  content:
                    type: array
                    items:
                      $ref: '#/components/schemas/EventSubscription'
        '401':
          $ref: '#/components/responses/Unauthorized'
    post:
      operationId: createEventSubscription
      tags:
      - Event Subscriptions
      summary: Create an event subscription
      description: Registers an HTTPS callback URL for an event type. lexoffice POSTs a webhook payload to the callback URL when a matching event fires.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/EventSubscriptionInput'
      responses:
        '200':
          description: The created event subscription.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EventSubscription'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /event-subscriptions/{id}:
    parameters:
    - $ref: '#/components/parameters/Id'
    get:
      operationId: getEventSubscription
      tags:
      - Event Subscriptions
      summary: Retrieve an event subscription
      responses:
        '200':
          description: The requested event subscription.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EventSubscription'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
    delete:
      operationId: deleteEventSubscription
      tags:
      - Event Subscriptions
      summary: Delete an event subscription
      responses:
        '204':
          description: The subscription was deleted.
        '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
    EventSubscriptionInput:
      type: object
      required:
      - eventType
      - callbackUrl
      properties:
        eventType:
          type: string
          description: The event to subscribe to, e.g. contact.created, contact.changed, invoice.created, invoice.status.changed, voucher.created.
          example: invoice.created
        callbackUrl:
          type: string
          format: uri
          description: HTTPS URL that lexoffice POSTs the webhook payload to.
    EventSubscription:
      allOf:
      - $ref: '#/components/schemas/EventSubscriptionInput'
      - type: object
        properties:
          subscriptionId:
            type: string
            format: uuid
          organizationId:
            type: string
            format: uuid
          createdDate:
            type: string
            format: date-time
  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'
  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`.'