openapi: 3.0.3
info:
  title: lexoffice (lexware Office) Public Contacts 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: Contacts
  description: Customers and vendors.
paths:
  /contacts:
    get:
      operationId: listContacts
      tags:
      - Contacts
      summary: Filter and list contacts
      description: Returns a paged list of contacts. Supports filter query parameters such as email, name, number, customer, and vendor.
      parameters:
      - name: email
        in: query
        required: false
        schema:
          type: string
      - name: name
        in: query
        required: false
        schema:
          type: string
      - name: number
        in: query
        required: false
        schema:
          type: integer
      - name: customer
        in: query
        required: false
        schema:
          type: boolean
      - name: vendor
        in: query
        required: false
        schema:
          type: boolean
      - $ref: '#/components/parameters/Page'
      - $ref: '#/components/parameters/Size'
      responses:
        '200':
          description: A page of contacts.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ContactPage'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/TooManyRequests'
    post:
      operationId: createContact
      tags:
      - Contacts
      summary: Create a contact
      description: Creates a new contact (customer and/or vendor).
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Contact'
      responses:
        '200':
          description: Reference to the created contact.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResourceReference'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/TooManyRequests'
  /contacts/{id}:
    parameters:
    - $ref: '#/components/parameters/Id'
    get:
      operationId: getContact
      tags:
      - Contacts
      summary: Retrieve a contact
      description: Retrieves a single contact by its UUID.
      responses:
        '200':
          description: The requested contact.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Contact'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
    put:
      operationId: updateContact
      tags:
      - Contacts
      summary: Update a contact
      description: Updates an existing contact. The current version number must be supplied for optimistic locking.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Contact'
      responses:
        '200':
          description: Reference to the updated contact.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResourceReference'
        '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
    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:
    ContactPage:
      type: object
      properties:
        content:
          type: array
          items:
            $ref: '#/components/schemas/Contact'
        totalPages:
          type: integer
        totalElements:
          type: integer
        size:
          type: integer
        number:
          type: integer
    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
    Contact:
      type: object
      properties:
        id:
          type: string
          format: uuid
          readOnly: true
        organizationId:
          type: string
          format: uuid
        version:
          type: integer
        roles:
          type: object
          properties:
            customer:
              type: object
              properties:
                number:
                  type: integer
            vendor:
              type: object
              properties:
                number:
                  type: integer
        company:
          type: object
          properties:
            name:
              type: string
            taxNumber:
              type: string
            vatRegistrationId:
              type: string
            allowTaxFreeInvoices:
              type: boolean
            contactPersons:
              type: array
              items:
                type: object
                properties:
                  salutation:
                    type: string
                  firstName:
                    type: string
                  lastName:
                    type: string
                  emailAddress:
                    type: string
                  phoneNumber:
                    type: string
        person:
          type: object
          properties:
            salutation:
              type: string
            firstName:
              type: string
            lastName:
              type: string
        addresses:
          type: object
          properties:
            billing:
              type: array
              items:
                $ref: '#/components/schemas/Address'
            shipping:
              type: array
              items:
                $ref: '#/components/schemas/Address'
        emailAddresses:
          type: object
          additionalProperties: true
        phoneNumbers:
          type: object
          additionalProperties: true
        note:
          type: string
        archived:
          type: boolean
          readOnly: true
    Address:
      type: object
      properties:
        supplement:
          type: string
        street:
          type: string
        zip:
          type: string
        city:
          type: string
        countryCode:
          type: string
          example: DE
  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`.'