openapi: 3.0.3
info:
  title: lexoffice (lexware Office) Public Contacts Profile 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: Profile
  description: Account profile and reference metadata.
paths:
  /profile:
    get:
      operationId: getProfile
      tags:
      - Profile
      summary: Retrieve the account profile
      description: Returns the connected organization's profile and connection metadata.
      responses:
        '200':
          description: The account profile.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Profile'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /countries:
    get:
      operationId: listCountries
      tags:
      - Profile
      summary: List countries
      description: Returns the list of countries supported by lexoffice with tax classification.
      responses:
        '200':
          description: A list of countries.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Country'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /posting-categories:
    get:
      operationId: listPostingCategories
      tags:
      - Profile
      summary: List posting categories
      description: Returns the posting categories used to classify voucher items for bookkeeping.
      responses:
        '200':
          description: A list of posting categories.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/PostingCategory'
        '401':
          $ref: '#/components/responses/Unauthorized'
components:
  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
    PostingCategory:
      type: object
      properties:
        id:
          type: string
          format: uuid
        name:
          type: string
        type:
          type: string
          enum:
          - income
          - outgo
        contactRequired:
          type: boolean
        splitAllowed:
          type: boolean
        groupName:
          type: string
    Country:
      type: object
      properties:
        countryCode:
          type: string
          example: DE
        countryNameEN:
          type: string
        countryNameDE:
          type: string
        taxClassification:
          type: string
          enum:
          - de
          - intraCommunity
          - thirdPartyCountry
    Profile:
      type: object
      properties:
        organizationId:
          type: string
          format: uuid
        companyName:
          type: string
        created:
          type: object
          properties:
            userId:
              type: string
              format: uuid
            userName:
              type: string
            userEmail:
              type: string
            date:
              type: string
              format: date-time
        connectionId:
          type: string
          format: uuid
        taxType:
          type: string
        smallBusiness:
          type: boolean
  responses:
    Unauthorized:
      description: Missing or invalid Bearer API key.
      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`.'