openapi: '3.1.0'
info:
  title: Advision360 Public API
  version: '1.0.0'
  summary: Integrate CRMs, broker pools, comparison portals and back-office tools with Advision360.
  description: |
    **Closed API.** The Advision360 Public API is available to partners and customers after explicit
    activation by Advision360. To request access, write to info@advision360.de with a short description
    of your integration. After activation you receive sandbox credentials (`sk_test_`); production
    credentials follow once your integration has been approved.

    The API exposes the business objects of an Advision360 company: contacts, leads, contracts,
    claims, commissions, documents, advice documentation, tasks, appointments, emails, insurer
    correspondence, e-signatures and the customer portal, plus webhooks and an event feed to keep
    external systems in sync.

    ## Connecting an AMS
    Agency management systems (AMS / Maklerverwaltungsprogramme) connect in three ways, which can be
    combined:

    | Way | Use it for |
    |---|---|
    | **REST sync** | Bidirectional, near real-time. Upsert by your own IDs (`PUT /external/{source}/...`), bulk endpoints, the `/events` feed or webhooks for changes, `/external-references` to rebuild ID mappings and `/sync/checkpoints` to resume. |
    | **Portfolio transfer** | Initial load and periodic reconciliation with GDV-Datensatz VU-Vermittler, BiPRO 430.4 or CSV files (`/portfolio-transfers`, `/exports`). |
    | **Managed connections** | Systems Advision360 already connects to natively (`/integrations/providers`), configured and monitored through `/integrations/connections`. |

    Insurer data arrives via BiPRO (`/bipro/deliveries`): contract documents, portfolio changes,
    collections, claims and commission statements are matched to contacts and contracts automatically.

    ## Base URL and versioning
    All endpoints live under `/api/public/v1`. Breaking changes ship as a new major path (`/v2`).
    Additive changes (new endpoints, new optional fields, new enum values) can appear at any time;
    clients must ignore unknown fields and treat unknown enum values gracefully.

    ## Authentication
    | Credential | Prefix | Use case |
    |---|---|---|
    | Secret API key | `sk_live_` / `sk_test_` | Server-to-server integration of one company. Issued on activation; company admins then manage keys in *Einstellungen → API*. Carries scopes. |
    | OAuth 2.0 access token | – | Partner applications that act for many brokers (authorization code + PKCE) or for one company (client credentials). |
    | Publishable key | `pk_live_` | Browser-safe, only for `POST /leads/intake` (website forms). Already in use today. |

    Send secret keys and access tokens as `Authorization: Bearer <token>`. Every request runs in the
    context of exactly one company; tokens issued for a user additionally respect that user's role
    permissions and data delegations.

    ## Scopes
    Scopes follow `<resource>:read` / `<resource>:write`. `write` implies `read`. See the
    `OAuth2` security scheme for the full list.

    ## Pagination
    List endpoints use cursor pagination: pass `limit` (1–200, default 50) and the `nextCursor` of the
    previous page as `cursor`. Responses look like `{ "data": [...], "pagination": { "nextCursor": "…", "hasMore": true } }`.
    Cursors are opaque and expire after 24 hours.

    ## Incremental sync
    Every resource has `createdAt` and `updatedAt`. Use `updatedSince` on list endpoints for delta
    sync and `GET /events` (or webhooks) to learn about deletions. Each resource can carry
    `externalReferences` (`source` + `externalId`) and offers an upsert endpoint
    `PUT /external/{source}/<resource>/{externalId}` (e.g. `PUT /external/my-crm/contacts/K-100234`) so your own IDs stay the primary key on your side.

    ## Dates, times and money
    * Dates without time (`format: date`) are calendar dates, e.g. `2026-10-15`.
    * Timestamps are RFC 3339 with offset, e.g. `2026-10-15T14:30:00+02:00`. Advision360 is a German
      system: wall-clock times are interpreted in `Europe/Berlin`. A timestamp sent without offset is
      treated as Europe/Berlin local time.
    * Amounts are decimals in EUR with two fraction digits (`"112.00"`), sent as strings to avoid
      floating point issues.

    ## Errors
    Errors use [RFC 9457](https://www.rfc-editor.org/rfc/rfc9457) `application/problem+json`.
    Validation errors (`422`) list every invalid field in `errors[]` with a stable machine `code`.

    ## Rate limits
    Default: 600 requests per minute per credential (sliding window). Every authenticated response
    carries `RateLimit-Limit` and `RateLimit-Remaining`. Exceeding the limit returns `429` with
    `Retry-After`.

    ## Idempotency
    `POST` requests accept an `Idempotency-Key` header (UUID recommended). Repeating a request with the
    same key within 24 hours returns the original response instead of creating a duplicate.

    ## Optimistic concurrency
    Single-resource responses carry an `ETag`. Send it back as `If-Match` on `PATCH`/`DELETE` to avoid
    overwriting concurrent changes (`412 Precondition Failed`).

    ## Language
    Machine values (enum keys, codes) are English and stable. Human-readable labels (`…Label` fields)
    follow `Accept-Language` (`de` default, `en`). User-generated content (notes, names, custom texts)
    is returned as entered.
  contact:
    name: Advision360 Integrations
    email: info@advision360.de
    url: https://www.advision360.de
  license:
    name: Proprietary
    identifier: LicenseRef-Advision360-Proprietary
servers:
- url: https://app.advision360.de/api/public/v1
  description: Production
- url: https://sandbox.advision360.de/api/public/v1
  description: Sandbox (separate data, test keys `sk_test_`)
security:
- ApiKey: []
- OAuth2: []
tags:
- name: Account
  description: The company behind the credential, its licensed features and team members.
- name: Contacts
  description: |
    Private persons and businesses with their static fields (grouped like in the app: address,
    personal, health, profession, bank, income, identity, social insurance & tax, pension,
    business), phones, relationships, household finances, tags, labels and custom fields.
- name: Contact catalog
  description: Field definitions that describe the contact payload. Cache these responses.
- name: Timeline
  description: Notes, emails and system events of a contact.
- name: Customer portal
  description: Invite contacts to the customer portal and handle the data changes they request there.
- name: Leads
  description: Prospects in the lead pipeline, website lead intake and conversion into contacts.
- name: Contracts
  description: Insurance and finance contracts of contacts, including type-specific data and the status workflow.
- name: Contract catalog
  description: Contract types with their field schemas and the insurer catalog.
- name: Offers
  description: Comparison and application processes run through connected platforms.
- name: Documents
  description: Files of contacts and contracts.
- name: Document AI
  description: Read contract data from policies and offers.
- name: Insurer correspondence
  description: Standardized emails to insurers (changes, cancellations, claims, ...).
- name: E-signature
  description: Send documents for legally binding electronic signature.
- name: Tasks
  description: To-dos of the team, linked to contacts or leads.
- name: Appointments
  description: Calendar of the team incl. recurring appointments.
- name: Claims
  description: Insurance claims of contacts, from the first notice to settlement.
- name: Commissions
  description: Commission statements of insurers, entries per contract and cancellation liability.
- name: AMS connections
  description: Agency management systems, broker pools and platforms connected to Advision360, their sync runs and field mappings.
- name: Portfolio transfer
  description: Import and export of portfolios as GDV-Datensatz VU-Vermittler, BiPRO 430.4 or CSV.
- name: BiPRO
  description: Deliveries from insurers via BiPRO 430 transfer services.
- name: Sync protocol
  description: Building blocks for bidirectional connectors (ID mapping, checkpoints).
- name: Emails
  description: Email threads of the company's mailboxes, sending and templates.
- name: Marketing
  description: Segments, email funnels and opt-outs.
- name: Automations
  description: Workflow automations and their runs.
- name: Calculators
  description: Calculators and needs analyses with their saved results.
- name: Advice documentation
  description: Documented consultations according to IDD.
- name: Landing pages
  description: Lead-generating landing pages and their submissions.
- name: Document generation
  description: Letters, agreements and protocols generated from company templates.
- name: Imports
  description: Contact imports from CSV and Excel.
- name: Reports
  description: Portfolio, renewals, coverage gaps, pipeline and team activity.
- name: Search
  description: Full-text search across the company.
- name: Privacy
  description: GDPR data subject requests.
- name: Administration
  description: Roles, groups of companies, custom fields, lead stages and tags.
- name: Reference data
  description: Value lists with localized labels.
- name: Batch
  description: Several requests in one call.
- name: Events
  description: Change feed of the company. Same payloads as webhooks.
- name: Webhooks
  description: Push notifications to your HTTPS endpoint, signed with HMAC-SHA256.
x-tagGroups:
- name: Basics
  tags:
  - Account
  - Events
  - Webhooks
  - Batch
  - Reference data
- name: AMS & portfolio data
  tags:
  - AMS connections
  - Portfolio transfer
  - BiPRO
  - Sync protocol
- name: Customers
  tags:
  - Contacts
  - Contact catalog
  - Timeline
  - Customer portal
  - Leads
  - Search
- name: Portfolio
  tags:
  - Contracts
  - Contract catalog
  - Claims
  - Commissions
  - Offers
  - Documents
  - Document AI
  - Document generation
- name: Advice & sales
  tags:
  - Calculators
  - Advice documentation
  - Landing pages
- name: Communication
  tags:
  - Emails
  - Insurer correspondence
  - E-signature
  - Marketing
  - Automations
- name: Work
  tags:
  - Tasks
  - Appointments
- name: Administration
  tags:
  - Administration
  - Imports
  - Reports
  - Privacy
paths:
  /me:
    get:
      tags:
      - Account
      operationId: getCurrentCredential
      summary: Who am I
      description: Returns the company, the acting user (if any) and the scopes of the current credential. Use it to verify
        a key.
      responses:
        '200':
          description: Credential context.
          headers:
            RateLimit-Limit:
              $ref: '#/components/headers/RateLimitLimit'
            RateLimit-Remaining:
              $ref: '#/components/headers/RateLimitRemaining'
            RateLimit-Reset:
              $ref: '#/components/headers/RateLimitReset'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CredentialContext'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /events:
    get:
      tags:
      - Events
      operationId: listEvents
      summary: Event feed
      description: |
        Chronological feed of everything that happened in the company, including deletions. Same
        payloads as webhooks. Poll it with the last `nextCursor` to never miss a change, even when your
        webhook endpoint was down. Events are retained for 30 days.
      security:
      - ApiKey: []
      - OAuth2:
        - events:read
      parameters:
      - $ref: '#/components/parameters/Cursor'
      - $ref: '#/components/parameters/Limit'
      - name: types
        in: query
        description: Comma-separated event types, e.g. `contact.created,contract.updated`.
        schema:
          type: string
      - name: since
        in: query
        description: Start at this timestamp when no cursor is known yet.
        schema:
          type: string
          format: date-time
      responses:
        '200':
          description: A page of events.
          content:
            application/json:
              schema:
                type: object
                required:
                - data
                - pagination
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Event'
                  pagination:
                    $ref: '#/components/schemas/Pagination'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
  /event-types:
    get:
      tags:
      - Events
      operationId: listEventTypes
      summary: Event type catalog
      responses:
        '200':
          description: All event types that can be subscribed to.
          content:
            application/json:
              schema:
                type: object
                required:
                - data
                properties:
                  data:
                    type: array
                    items:
                      type: object
                      required:
                      - type
                      - description
                      - scope
                      properties:
                        type:
                          $ref: '#/components/schemas/EventType'
                        description:
                          type: string
                        scope:
                          type: string
                          description: Scope needed to receive the event.
                          examples:
                          - contacts:read
        '401':
          $ref: '#/components/responses/Unauthorized'
  /webhook-endpoints:
    get:
      tags:
      - Webhooks
      operationId: listWebhookEndpoints
      summary: List webhook endpoints
      security:
      - ApiKey: []
      - OAuth2:
        - webhooks:read
      parameters:
      - $ref: '#/components/parameters/Cursor'
      - $ref: '#/components/parameters/Limit'
      responses:
        '200':
          description: A page of webhook endpoints.
          content:
            application/json:
              schema:
                type: object
                required:
                - data
                - pagination
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/WebhookEndpoint'
                  pagination:
                    $ref: '#/components/schemas/Pagination'
        '401':
          $ref: '#/components/responses/Unauthorized'
    post:
      tags:
      - Webhooks
      operationId: createWebhookEndpoint
      summary: Register a webhook endpoint
      description: |
        Registers an HTTPS URL that receives event notifications. The response contains the signing
        secret **once**; store it to verify the `Advision360-Signature` header.
      security:
      - ApiKey: []
      - OAuth2:
        - webhooks:write
      parameters:
      - $ref: '#/components/parameters/IdempotencyKey'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/WebhookEndpointInput'
      responses:
        '201':
          description: Created. `secret` is only returned here.
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/WebhookEndpoint'
                - type: object
                  required:
                  - secret
                  properties:
                    secret:
                      type: string
                      examples:
                      - whsec_3f9a2c...
        '401':
          $ref: '#/components/responses/Unauthorized'
        '422':
          $ref: '#/components/responses/ValidationFailed'
  /webhook-endpoints/{webhookEndpointId}:
    parameters:
    - name: webhookEndpointId
      in: path
      required: true
      schema:
        type: string
        format: uuid
    get:
      tags:
      - Webhooks
      operationId: getWebhookEndpoint
      summary: Get a webhook endpoint
      security:
      - ApiKey: []
      - OAuth2:
        - webhooks:read
      responses:
        '200':
          description: The webhook endpoint.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WebhookEndpoint'
        '404':
          $ref: '#/components/responses/NotFound'
    patch:
      tags:
      - Webhooks
      operationId: updateWebhookEndpoint
      summary: Update a webhook endpoint
      security:
      - ApiKey: []
      - OAuth2:
        - webhooks:write
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/WebhookEndpointPatch'
      responses:
        '200':
          description: Updated.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WebhookEndpoint'
        '404':
          $ref: '#/components/responses/NotFound'
        '422':
          $ref: '#/components/responses/ValidationFailed'
    delete:
      tags:
      - Webhooks
      operationId: deleteWebhookEndpoint
      summary: Delete a webhook endpoint
      security:
      - ApiKey: []
      - OAuth2:
        - webhooks:write
      responses:
        '204':
          description: Deleted.
        '404':
          $ref: '#/components/responses/NotFound'
  /webhook-endpoints/{webhookEndpointId}/rotate-secret:
    parameters:
    - name: webhookEndpointId
      in: path
      required: true
      schema:
        type: string
        format: uuid
    post:
      tags:
      - Webhooks
      operationId: rotateWebhookSecret
      summary: Rotate the signing secret
      description: Issues a new secret. The old one stays valid for 24 hours so you can roll over without downtime.
      security:
      - ApiKey: []
      - OAuth2:
        - webhooks:write
      responses:
        '200':
          description: New secret.
          content:
            application/json:
              schema:
                type: object
                required:
                - secret
                - previousSecretExpiresAt
                properties:
                  secret:
                    type: string
                  previousSecretExpiresAt:
                    type: string
                    format: date-time
        '404':
          $ref: '#/components/responses/NotFound'
  /webhook-endpoints/{webhookEndpointId}/test:
    parameters:
    - name: webhookEndpointId
      in: path
      required: true
      schema:
        type: string
        format: uuid
    post:
      tags:
      - Webhooks
      operationId: sendTestWebhook
      summary: Send a test event
      description: Sends a `ping` event to the endpoint and returns the delivery result.
      security:
      - ApiKey: []
      - OAuth2:
        - webhooks:write
      responses:
        '200':
          description: Delivery attempt.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WebhookDelivery'
        '404':
          $ref: '#/components/responses/NotFound'
  /webhook-endpoints/{webhookEndpointId}/deliveries:
    parameters:
    - name: webhookEndpointId
      in: path
      required: true
      schema:
        type: string
        format: uuid
    get:
      tags:
      - Webhooks
      operationId: listWebhookDeliveries
      summary: Delivery log
      description: Last 30 days of delivery attempts, newest first.
      security:
      - ApiKey: []
      - OAuth2:
        - webhooks:read
      parameters:
      - $ref: '#/components/parameters/Cursor'
      - $ref: '#/components/parameters/Limit'
      - name: status
        in: query
        schema:
          type: string
          enum:
          - succeeded
          - failed
          - pending
      responses:
        '200':
          description: A page of deliveries.
          content:
            application/json:
              schema:
                type: object
                required:
                - data
                - pagination
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/WebhookDelivery'
                  pagination:
                    $ref: '#/components/schemas/Pagination'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /webhook-endpoints/{webhookEndpointId}/deliveries/{deliveryId}/retry:
    parameters:
    - name: webhookEndpointId
      in: path
      required: true
      schema:
        type: string
        format: uuid
    - name: deliveryId
      in: path
      required: true
      schema:
        type: string
        format: uuid
    post:
      tags:
      - Webhooks
      operationId: retryWebhookDelivery
      summary: Redeliver an event
      security:
      - ApiKey: []
      - OAuth2:
        - webhooks:write
      responses:
        '202':
          description: Redelivery queued.
        '404':
          $ref: '#/components/responses/NotFound'
  /company:
    get:
      tags:
      - Account
      operationId: getCompany
      summary: Company profile
      description: Name, address, public links and the licensed features of the company. Features decide which endpoints are
        usable (e.g. `leads`, `customer_portal`, `digital_signature`).
      security:
      - ApiKey: []
      - OAuth2:
        - company:read
      responses:
        '200':
          description: The company.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Company'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /users:
    get:
      tags:
      - Account
      operationId: listUsers
      summary: Team members
      description: Users of the company, e.g. to map owners and assignees to your system.
      security:
      - ApiKey: []
      - OAuth2:
        - users:read
      parameters:
      - $ref: '#/components/parameters/Cursor'
      - $ref: '#/components/parameters/Limit'
      - name: status
        in: query
        schema:
          type: string
          enum:
          - active
          - inactive
          - suspended
      - name: email
        in: query
        schema:
          type: string
          format: email
      responses:
        '200':
          description: A page of users.
          content:
            application/json:
              schema:
                type: object
                required:
                - data
                - pagination
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/User'
                  pagination:
                    $ref: '#/components/schemas/Pagination'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /users/{userId}:
    parameters:
    - name: userId
      in: path
      required: true
      schema:
        type: string
        format: uuid
    get:
      tags:
      - Account
      operationId: getUser
      summary: Get a team member
      security:
      - ApiKey: []
      - OAuth2:
        - users:read
      responses:
        '200':
          description: The user.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'
        '404':
          $ref: '#/components/responses/NotFound'
  /contacts:
    get:
      tags:
      - Contacts
      operationId: listContacts
      summary: List contacts
      description: |
        Contacts visible to the credential. User-bound credentials only see the user's own contacts,
        contacts delegated to them, or all contacts if the user may see everything.

        Sensitive groups (`identity`, `health`, `bank`, `income`) are only included with the scope `contacts.sensitive:read`.
      security:
      - ApiKey: []
      - OAuth2:
        - contacts:read
      parameters:
      - $ref: '#/components/parameters/Cursor'
      - $ref: '#/components/parameters/Limit'
      - $ref: '#/components/parameters/UpdatedSince'
      - name: q
        in: query
        description: Full-text search over name, company name, email, phone, city, street, profession and tags.
        schema:
          type: string
          minLength: 2
      - name: type
        in: query
        schema:
          $ref: '#/components/schemas/ContactType'
      - name: email
        in: query
        description: Exact email match (case-insensitive).
        schema:
          type: string
          format: email
      - name: phone
        in: query
        description: Exact phone match after E.164 normalization.
        schema:
          type: string
      - name: tag
        in: query
        description: Comma-separated tag names; contacts must carry all of them.
        schema:
          type: string
      - name: label
        in: query
        description: Comma-separated label colors.
        schema:
          type: string
      - name: ownerId
        in: query
        schema:
          type: string
          format: uuid
      - name: sort
        in: query
        schema:
          type: string
          enum:
          - name
          - -name
          - createdAt
          - -createdAt
          - updatedAt
          - -updatedAt
          default: -createdAt
      - name: fields
        in: query
        description: 'Comma-separated field groups to return, e.g. `address,personal`. Default: all groups the credential
          may read.'
        schema:
          type: string
      responses:
        '200':
          description: A page of contacts.
          content:
            application/json:
              schema:
                type: object
                required:
                - data
                - pagination
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Contact'
                  pagination:
                    $ref: '#/components/schemas/Pagination'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '429':
          $ref: '#/components/responses/TooManyRequests'
    post:
      tags:
      - Contacts
      operationId: createContact
      summary: Create a contact
      description: |
        Creates a private person or a business. Required: `firstName` and `lastName` for private
        contacts, `business.companyName` for business contacts. Static fields that do not apply to the
        contact type (e.g. `health` for a business) are rejected with `422`.

        Without `ownerId` the contact belongs to the acting user, or to the company admin for
        company-level keys.
      security:
      - ApiKey: []
      - OAuth2:
        - contacts:write
      parameters:
      - $ref: '#/components/parameters/IdempotencyKey'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ContactCreate'
            examples:
              private:
                summary: Private person
                value:
                  type: private
                  firstName: Manni
                  lastName: Mustermann
                  email: manni@example.com
                  phones:
                  - number: +49 177 5935467
                    type: mobile
                    isPrimary: true
                  address:
                    street: Teststraße
                    houseNumber: '200'
                    zipCode: '01069'
                    city: Dresden
                    country: DE
                  personal:
                    salutation: mr
                    dateOfBirth: '1980-04-12'
                    maritalStatus: married
                  profession:
                    employmentStatus: employed
                    profession: Ingenieur
                  tags:
                  - Neukunde 2026
                  externalReferences:
                  - source: my-crm
                    externalId: K-100234
              business:
                summary: Business
                value:
                  type: business
                  business:
                    companyName: Mustermann Bau GmbH
                    legalForm: gmbh
                  firstName: Erika
                  lastName: Mustermann
                  email: info@mustermann-bau.de
                  address:
                    street: Industriestraße
                    houseNumber: '5'
                    zipCode: '01109'
                    city: Dresden
                    country: DE
      responses:
        '201':
          description: Created.
          headers:
            Location:
              $ref: '#/components/headers/Location'
            ETag:
              $ref: '#/components/headers/ETag'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Contact'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '409':
          $ref: '#/components/responses/Conflict'
        '422':
          $ref: '#/components/responses/ValidationFailed'
  /contacts/{contactId}:
    parameters:
    - $ref: '#/components/parameters/ContactId'
    get:
      tags:
      - Contacts
      operationId: getContact
      summary: Get a contact
      security:
      - ApiKey: []
      - OAuth2:
        - contacts:read
      parameters:
      - name: fields
        in: query
        description: 'Comma-separated field groups to return, e.g. `address,personal`. Default: all groups the credential may read.'
        schema:
          type: string
      responses:
        '200':
          description: The contact.
          headers:
            ETag:
              $ref: '#/components/headers/ETag'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Contact'
        '404':
          $ref: '#/components/responses/NotFound'
    patch:
      tags:
      - Contacts
      operationId: updateContact
      summary: Update a contact
      description: |
        JSON merge patch: send only what changes, `null` clears a field. Field groups are merged key by
        key (`{"address": {"city": "Leipzig"}}` keeps the street). `tags` and `labels` replace the whole
        list; `customFields` is merged by key. Phones are managed via `/contacts/{contactId}/phones`.

        `writeMode: fill_empty_only` only fills fields that are empty today, which is handy when your
        system is not the leading one.
      security:
      - ApiKey: []
      - OAuth2:
        - contacts:write
      parameters:
      - $ref: '#/components/parameters/IfMatch'
      requestBody:
        required: true
        content:
          application/merge-patch+json:
            schema:
              $ref: '#/components/schemas/ContactPatch'
      responses:
        '200':
          description: Updated.
          headers:
            ETag:
              $ref: '#/components/headers/ETag'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Contact'
        '404':
          $ref: '#/components/responses/NotFound'
        '412':
          $ref: '#/components/responses/PreconditionFailed'
        '422':
          $ref: '#/components/responses/ValidationFailed'
    delete:
      tags:
      - Contacts
      operationId: deleteContact
      summary: Delete a contact
      description: |
        Permanently deletes the contact **including its contracts, documents, notes and portal access**.
        This cannot be undone. Emits `contact.deleted`.
      security:
      - ApiKey: []
      - OAuth2:
        - contacts:write
      parameters:
      - $ref: '#/components/parameters/IfMatch'
      responses:
        '204':
          description: Deleted.
        '404':
          $ref: '#/components/responses/NotFound'
        '412':
          $ref: '#/components/responses/PreconditionFailed'
  /external/{source}/contacts/{externalId}:
    parameters:
    - $ref: '#/components/parameters/ExternalSource'
    - $ref: '#/components/parameters/ExternalId'
    get:
      tags:
      - Contacts
      operationId: getContactByExternalId
      summary: Get a contact by your ID
      security:
      - ApiKey: []
      - OAuth2:
        - contacts:read
      responses:
        '200':
          description: The contact.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Contact'
        '404':
          $ref: '#/components/responses/NotFound'
    put:
      tags:
      - Contacts
      operationId: upsertContactByExternalId
      summary: Create or update a contact by your ID
      description: |
        Idempotent sync endpoint. Creates the contact when no contact carries this external reference,
        otherwise updates it with the body. Use `writeMode: fill_empty_only` if Advision360 data must not
        be overwritten. Phones in the body replace the contact's phones.
      security:
      - ApiKey: []
      - OAuth2:
        - contacts:write
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ContactUpsert'
      responses:
        '200':
          description: Updated.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Contact'
        '201':
          description: Created.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Contact'
        '422':
          $ref: '#/components/responses/ValidationFailed'
  /contacts/bulk:
    post:
      tags:
      - Contacts
      operationId: bulkUpsertContacts
      summary: Upsert up to 100 contacts
      description: |
        Same semantics as `PUT /external/{source}/contacts/{externalId}` for many contacts in one call,
        e.g. for an initial load. Items are processed independently; the response reports each item.
      security:
      - ApiKey: []
      - OAuth2:
        - contacts:write
      parameters:
      - $ref: '#/components/parameters/IdempotencyKey'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - items
              properties:
                items:
                  type: array
                  minItems: 1
                  maxItems: 100
                  items:
                    allOf:
                    - type: object
                      required:
                      - externalReference
                      properties:
                        externalReference:
                          $ref: '#/components/schemas/ExternalReference'
                    - $ref: '#/components/schemas/ContactUpsert'
      responses:
        '200':
          description: Per-item results in request order.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BulkResult'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /contacts/match:
    post:
      tags:
      - Contacts
      operationId: matchContacts
      summary: Find possible duplicates
      description: |
        Returns existing contacts that match the given data (email, normalized phone, name plus date of
        birth, company name), best match first. Call it before creating contacts from a foreign system.
      security:
      - ApiKey: []
      - OAuth2:
        - contacts:read
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              minProperties: 1
              properties:
                type:
                  $ref: '#/components/schemas/ContactType'
                email:
                  type: string
                  format: email
                phone:
                  type: string
                firstName:
                  type: string
                lastName:
                  type: string
                dateOfBirth:
                  type: string
                  format: date
                companyName:
                  type: string
      responses:
        '200':
          description: Candidates.
          content:
            application/json:
              schema:
                type: object
                required:
                - data
                properties:
                  data:
                    type: array
                    items:
                      type: object
                      required:
                      - contact
                      - matchedBy
                      - score
                      properties:
                        contact:
                          $ref: '#/components/schemas/ContactSummary'
                        matchedBy:
                          type: array
                          items:
                            type: string
                            enum:
                            - email
                            - phone
                            - name_and_birthdate
                            - company_name
                            - external_reference
                        score:
                          type: number
                          minimum: 0
                          maximum: 1
        '401':
          $ref: '#/components/responses/Unauthorized'
  /contacts/{contactId}/phones:
    parameters:
    - $ref: '#/components/parameters/ContactId'
    post:
      tags:
      - Contacts
      operationId: addContactPhone
      summary: Add a phone number
      security:
      - ApiKey: []
      - OAuth2:
        - contacts:write
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PhoneInput'
      responses:
        '201':
          description: Added.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Phone'
        '422':
          $ref: '#/components/responses/ValidationFailed'
  /contacts/{contactId}/phones/{phoneId}:
    parameters:
    - $ref: '#/components/parameters/ContactId'
    - name: phoneId
      in: path
      required: true
      schema:
        type: string
        format: uuid
    patch:
      tags:
      - Contacts
      operationId: updateContactPhone
      summary: Update a phone number
      security:
      - ApiKey: []
      - OAuth2:
        - contacts:write
      requestBody:
        required: true
        content:
          application/merge-patch+json:
            schema:
              $ref: '#/components/schemas/PhoneInput'
      responses:
        '200':
          description: Updated.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Phone'
        '404':
          $ref: '#/components/responses/NotFound'
        '422':
          $ref: '#/components/responses/ValidationFailed'
    delete:
      tags:
      - Contacts
      operationId: deleteContactPhone
      summary: Remove a phone number
      security:
      - ApiKey: []
      - OAuth2:
        - contacts:write
      responses:
        '204':
          description: Removed.
        '404':
          $ref: '#/components/responses/NotFound'
  /contacts/{contactId}/relationships:
    parameters:
    - $ref: '#/components/parameters/ContactId'
    get:
      tags:
      - Contacts
      operationId: listContactRelationships
      summary: Family and employer relationships
      description: Relationships seen from this contact (`role` is the role of the other contact).
      security:
      - ApiKey: []
      - OAuth2:
        - contacts:read
      responses:
        '200':
          description: Relationships.
          content:
            application/json:
              schema:
                type: object
                required:
                - data
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/ContactRelationship'
        '401':
          $ref: '#/components/responses/Unauthorized'
    post:
      tags:
      - Contacts
      operationId: createContactRelationship
      summary: Link two contacts
      description: |
        * `partner`: spouse or partner (symmetric).
        * `child`: the related contact is a child of this contact.
        * `parent`: the related contact is a parent of this contact.
        * `employer`: the related contact is the (business) employer of this contact; `position` is the job title.
      security:
      - ApiKey: []
      - OAuth2:
        - contacts:write
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - relatedContactId
              - role
              properties:
                relatedContactId:
                  $ref: '#/components/schemas/Uuid'
                role:
                  $ref: '#/components/schemas/ContactRelationshipRole'
                position:
                  type: string
                  maxLength: 150
                  description: Only for `employer`.
      responses:
        '201':
          description: Linked.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ContactRelationship'
        '409':
          $ref: '#/components/responses/Conflict'
        '422':
          $ref: '#/components/responses/ValidationFailed'
  /contacts/{contactId}/relationships/{relationshipId}:
    parameters:
    - $ref: '#/components/parameters/ContactId'
    - name: relationshipId
      in: path
      required: true
      schema:
        type: string
        format: uuid
    delete:
      tags:
      - Contacts
      operationId: deleteContactRelationship
      summary: Unlink two contacts
      security:
      - ApiKey: []
      - OAuth2:
        - contacts:write
      responses:
        '204':
          description: Unlinked.
        '404':
          $ref: '#/components/responses/NotFound'
  /contacts/{contactId}/finance:
    parameters:
    - $ref: '#/components/parameters/ContactId'
    get:
      tags:
      - Contacts
      operationId: getContactFinance
      summary: Household finances
      description: Income, expenses, assets, liabilities and real estate of a private contact, with computed totals.
      security:
      - ApiKey: []
      - OAuth2:
        - contacts:read
      responses:
        '200':
          description: The finance profile.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ContactFinance'
        '404':
          $ref: '#/components/responses/NotFound'
        '422':
          description: Business contacts have no household finances.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
    put:
      tags:
      - Contacts
      operationId: replaceContactFinance
      summary: Replace household finances
      description: Replaces all lists that are present in the body. Omitted lists stay unchanged; an empty list clears it.
      security:
      - ApiKey: []
      - OAuth2:
        - contacts:write
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ContactFinanceInput'
      responses:
        '200':
          description: Saved.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ContactFinance'
        '422':
          $ref: '#/components/responses/ValidationFailed'
  /contacts/{contactId}/activities:
    parameters:
    - $ref: '#/components/parameters/ContactId'
    get:
      tags:
      - Timeline
      operationId: listContactActivities
      summary: Contact timeline
      description: Notes, emails and system events of a contact, newest first.
      security:
      - ApiKey: []
      - OAuth2:
        - activities:read
      parameters:
      - $ref: '#/components/parameters/Cursor'
      - $ref: '#/components/parameters/Limit'
      - name: filter
        in: query
        schema:
          type: string
          enum:
          - notes
          - emails
          - system
      responses:
        '200':
          description: A page of activities.
          content:
            application/json:
              schema:
                type: object
                required:
                - data
                - pagination
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Activity'
                  pagination:
                    $ref: '#/components/schemas/Pagination'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /contacts/{contactId}/notes:
    parameters:
    - $ref: '#/components/parameters/ContactId'
    post:
      tags:
      - Timeline
      operationId: createContactNote
      summary: Add a note
      description: Adds a note to the timeline, e.g. a call log from your telephony system. Markdown is not rendered; line
        breaks are kept.
      security:
      - ApiKey: []
      - OAuth2:
        - activities:write
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - content
              properties:
                content:
                  type: string
                  maxLength: 50000
                occurredAt:
                  type: string
                  format: date-time
                  description: When it happened. Defaults to now.
                externalReferences:
                  type: array
                  items:
                    $ref: '#/components/schemas/ExternalReference'
      responses:
        '201':
          description: Added.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Activity'
        '422':
          $ref: '#/components/responses/ValidationFailed'
  /contacts/{contactId}/notes/{noteId}:
    parameters:
    - $ref: '#/components/parameters/ContactId'
    - name: noteId
      in: path
      required: true
      schema:
        type: string
        format: uuid
    patch:
      tags:
      - Timeline
      operationId: updateContactNote
      summary: Edit a note
      security:
      - ApiKey: []
      - OAuth2:
        - activities:write
      requestBody:
        required: true
        content:
          application/merge-patch+json:
            schema:
              type: object
              required:
              - content
              properties:
                content:
                  type: string
                  maxLength: 50000
      responses:
        '200':
          description: Updated.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Activity'
        '404':
          $ref: '#/components/responses/NotFound'
    delete:
      tags:
      - Timeline
      operationId: deleteContactNote
      summary: Delete a note
      description: Only notes can be deleted; system entries and emails are immutable.
      security:
      - ApiKey: []
      - OAuth2:
        - activities:write
      responses:
        '204':
          description: Deleted.
        '404':
          $ref: '#/components/responses/NotFound'
  /contacts/{contactId}/portal-access:
    parameters:
    - $ref: '#/components/parameters/ContactId'
    get:
      tags:
      - Customer portal
      operationId: getPortalAccess
      summary: Portal access of a contact
      security:
      - ApiKey: []
      - OAuth2:
        - contacts:read
      responses:
        '200':
          description: Current access.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PortalAccess'
        '404':
          $ref: '#/components/responses/NotFound'
    post:
      tags:
      - Customer portal
      operationId: invitePortalAccess
      summary: Invite to the customer portal
      description: Sends the portal invitation email to the contact's email address, or re-sends it while the access is `pending`.
      security:
      - ApiKey: []
      - OAuth2:
        - portal:write
      requestBody:
        required: false
        content:
          application/json:
            schema:
              type: object
              properties:
                email:
                  type: string
                  format: email
                  description: Overrides the contact email for this invitation.
      responses:
        '201':
          description: Invitation sent.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PortalAccess'
        '409':
          $ref: '#/components/responses/Conflict'
        '422':
          $ref: '#/components/responses/ValidationFailed'
    delete:
      tags:
      - Customer portal
      operationId: revokePortalAccess
      summary: Revoke portal access
      security:
      - ApiKey: []
      - OAuth2:
        - portal:write
      responses:
        '204':
          description: Revoked.
        '404':
          $ref: '#/components/responses/NotFound'
  /portal-change-requests:
    get:
      tags:
      - Customer portal
      operationId: listPortalChangeRequests
      summary: Data changes requested by customers
      description: Changes customers submitted in the portal (address, name, email, ...). They take effect only after approval.
      security:
      - ApiKey: []
      - OAuth2:
        - contacts:read
      parameters:
      - $ref: '#/components/parameters/Cursor'
      - $ref: '#/components/parameters/Limit'
      - $ref: '#/components/parameters/ContactIdFilter'
      - name: status
        in: query
        schema:
          type: string
          enum:
          - pending
          - approved
          - rejected
          - withdrawn
          default: pending
      responses:
        '200':
          description: A page of change requests.
          content:
            application/json:
              schema:
                type: object
                required:
                - data
                - pagination
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/PortalChangeRequest'
                  pagination:
                    $ref: '#/components/schemas/Pagination'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /portal-change-requests/{changeRequestId}/{decision}:
    parameters:
    - name: changeRequestId
      in: path
      required: true
      schema:
        type: string
        format: uuid
    - name: decision
      in: path
      required: true
      schema:
        type: string
        enum:
        - approve
        - reject
    post:
      tags:
      - Customer portal
      operationId: decidePortalChangeRequest
      summary: Approve or reject a change request
      security:
      - ApiKey: []
      - OAuth2:
        - contacts:write
      requestBody:
        required: false
        content:
          application/json:
            schema:
              type: object
              properties:
                reason:
                  type: string
                  maxLength: 1000
                  description: Shown to the customer on rejection.
      responses:
        '200':
          description: Decided.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PortalChangeRequest'
        '409':
          $ref: '#/components/responses/Conflict'
  /contact-fields:
    get:
      tags:
      - Contact catalog
      operationId: listContactFields
      summary: Static contact field catalog
      description: |
        Every static field with its group, data type, options and the contact types it applies to.
        Field keys equal the property names inside the contact's field groups. Cache the response.
      security:
      - ApiKey: []
      - OAuth2:
        - contacts:read
      responses:
        '200':
          description: The catalog.
          content:
            application/json:
              schema:
                type: object
                required:
                - data
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/ContactFieldDefinition'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /custom-fields:
    get:
      tags:
      - Contact catalog
      operationId: listCustomFields
      summary: Custom field definitions
      description: Company-specific fields (max. 10). Values are sent in `Contact.customFields` keyed by `key`.
      security:
      - ApiKey: []
      - OAuth2:
        - contacts:read
      responses:
        '200':
          description: Definitions in display order.
          content:
            application/json:
              schema:
                type: object
                required:
                - data
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/CustomFieldDefinition'
        '401':
          $ref: '#/components/responses/Unauthorized'
    post:
      tags:
      - Administration
      operationId: createCustomField
      summary: Add a custom field
      security:
      - ApiKey: []
      - OAuth2:
        - admin:write
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CustomFieldDefinitionInput'
      responses:
        '201':
          description: Created.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CustomFieldDefinition'
        '409':
          description: The company already has 10 custom fields or the key is taken.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
        '422':
          $ref: '#/components/responses/ValidationFailed'
  /tags:
    get:
      tags:
      - Contact catalog
      operationId: listTags
      summary: Tags in use
      security:
      - ApiKey: []
      - OAuth2:
        - contacts:read
      parameters:
      - $ref: '#/components/parameters/Search'
      - $ref: '#/components/parameters/Cursor'
      - $ref: '#/components/parameters/Limit'
      responses:
        '200':
          description: A page of tags.
          content:
            application/json:
              schema:
                type: object
                required:
                - data
                - pagination
                properties:
                  data:
                    type: array
                    items:
                      type: object
                      required:
                      - id
                      - name
                      - contactCount
                      properties:
                        id:
                          $ref: '#/components/schemas/Uuid'
                        name:
                          type: string
                          examples:
                          - Neukunde 2026
                        contactCount:
                          type: integer
                  pagination:
                    $ref: '#/components/schemas/Pagination'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /contracts:
    get:
      tags:
      - Contracts
      operationId: listContracts
      summary: List contracts
      security:
      - ApiKey: []
      - OAuth2:
        - contracts:read
      parameters:
      - $ref: '#/components/parameters/Cursor'
      - $ref: '#/components/parameters/Limit'
      - $ref: '#/components/parameters/UpdatedSince'
      - $ref: '#/components/parameters/ContactIdFilter'
      - name: q
        in: query
        description: Search in insurer name and policy number.
        schema:
          type: string
          minLength: 2
      - name: type
        in: query
        description: Comma-separated contract types.
        schema:
          type: string
          examples:
          - liability,household_contents
      - name: typeGroup
        in: query
        schema:
          $ref: '#/components/schemas/ContractTypeGroup'
      - name: status
        in: query
        description: Comma-separated statuses.
        schema:
          type: string
          examples:
          - policy,dormant
      - name: coverage
        in: query
        schema:
          $ref: '#/components/schemas/ContractCoverage'
      - name: insurerId
        in: query
        schema:
          type: string
          format: uuid
      - name: source
        in: query
        schema:
          $ref: '#/components/schemas/ContractSource'
      - name: sort
        in: query
        schema:
          type: string
          enum:
          - createdAt
          - -createdAt
          - updatedAt
          - -updatedAt
          - startDate
          - -startDate
          - endDate
          - -endDate
          - annualPremium
          - -annualPremium
          default: -createdAt
      responses:
        '200':
          description: A page of contracts.
          content:
            application/json:
              schema:
                type: object
                required:
                - data
                - pagination
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Contract'
                  pagination:
                    $ref: '#/components/schemas/Pagination'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
    post:
      tags:
      - Contracts
      operationId: createContract
      summary: Create a contract
      description: |
        Creates a contract for a contact. Without `status` the contract is created as `policy` (existing
        coverage), which requires `insurer`, `policyNumber`, `premium.gross` and `premium.paymentFrequency`.
        Pipeline statuses (`offer`, `application`) can be created with fewer fields, e.g. by comparison
        portals that hand over an application.

        The `type` must fit the contact type (see `GET /contract-types?contactType=`).
      security:
      - ApiKey: []
      - OAuth2:
        - contracts:write
      parameters:
      - $ref: '#/components/parameters/IdempotencyKey'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ContractCreate'
            example:
              contactId: 01a11123-2e86-713d-9536-4f9a063bab48
              type: liability
              insurer:
                insurerId: 0199f2a1-7c41-7b9e-8a55-1f2e3d4c5b6a
              policyNumber: PHV-2026-0042
              premium:
                gross: '112.00'
                paymentFrequency: annual
              startDate: '2026-01-01'
              typeSpecificData:
                coverageAmount: 10000000
                tariffType: family
                keyLossCoverage: true
              externalReferences:
              - source: my-crm
                externalId: V-55012
      responses:
        '201':
          description: Created.
          headers:
            Location:
              $ref: '#/components/headers/Location'
            ETag:
              $ref: '#/components/headers/ETag'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Contract'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          $ref: '#/components/responses/Conflict'
        '422':
          $ref: '#/components/responses/ValidationFailed'
  /contracts/{contractId}:
    parameters:
    - $ref: '#/components/parameters/ContractId'
    get:
      tags:
      - Contracts
      operationId: getContract
      summary: Get a contract
      security:
      - ApiKey: []
      - OAuth2:
        - contracts:read
      parameters:
      - name: expand
        in: query
        description: '`contact`, `insurer`, `documents` (comma-separated).'
        schema:
          type: string
      responses:
        '200':
          description: The contract.
          headers:
            ETag:
              $ref: '#/components/headers/ETag'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Contract'
        '404':
          $ref: '#/components/responses/NotFound'
    patch:
      tags:
      - Contracts
      operationId: updateContract
      summary: Update a contract
      description: |
        JSON merge patch (RFC 7396): send only the fields to change, `null` clears a field.
        `typeSpecificData` is merged key by key; changing `type` resets it. The status is changed
        through `POST /contracts/{contractId}/actions/{action}`, not here.

        Contracts with `providerManaged: true` are overwritten by the next provider sync; changes to
        provider-owned fields are accepted but can be reverted by the provider.
      security:
      - ApiKey: []
      - OAuth2:
        - contracts:write
      parameters:
      - $ref: '#/components/parameters/IfMatch'
      requestBody:
        required: true
        content:
          application/merge-patch+json:
            schema:
              $ref: '#/components/schemas/ContractPatch'
      responses:
        '200':
          description: Updated.
          headers:
            ETag:
              $ref: '#/components/headers/ETag'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Contract'
        '404':
          $ref: '#/components/responses/NotFound'
        '412':
          $ref: '#/components/responses/PreconditionFailed'
        '422':
          $ref: '#/components/responses/ValidationFailed'
    delete:
      tags:
      - Contracts
      operationId: deleteContract
      summary: Delete a contract
      description: Permanently deletes the contract. Linked documents stay with the contact and lose the contract link.
      security:
      - ApiKey: []
      - OAuth2:
        - contracts:write
      parameters:
      - $ref: '#/components/parameters/IfMatch'
      responses:
        '204':
          description: Deleted.
        '404':
          $ref: '#/components/responses/NotFound'
        '412':
          $ref: '#/components/responses/PreconditionFailed'
  /external/{source}/contracts/{externalId}:
    parameters:
    - $ref: '#/components/parameters/ExternalSource'
    - $ref: '#/components/parameters/ExternalId'
    get:
      tags:
      - Contracts
      operationId: getContractByExternalId
      summary: Get a contract by your ID
      security:
      - ApiKey: []
      - OAuth2:
        - contracts:read
      responses:
        '200':
          description: The contract.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Contract'
        '404':
          $ref: '#/components/responses/NotFound'
    put:
      tags:
      - Contracts
      operationId: upsertContractByExternalId
      summary: Create or update a contract by your ID
      description: |
        Idempotent sync endpoint. Creates the contract when no contract carries this external reference
        yet, otherwise replaces its writable fields with the body (`typeSpecificData` included). The
        contact is identified by `contactId` or `contactExternalReference`.
      security:
      - ApiKey: []
      - OAuth2:
        - contracts:write
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ContractUpsert'
      responses:
        '200':
          description: Updated.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Contract'
        '201':
          description: Created.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Contract'
        '404':
          $ref: '#/components/responses/NotFound'
        '422':
          $ref: '#/components/responses/ValidationFailed'
  /contracts/{contractId}/actions/{action}:
    parameters:
    - $ref: '#/components/parameters/ContractId'
    - name: action
      in: path
      required: true
      schema:
        $ref: '#/components/schemas/ContractAction'
    post:
      tags:
      - Contracts
      operationId: runContractAction
      summary: Change the contract status
      description: |
        Runs a status transition. `allowedActions` on the contract lists what is possible right now.

        | Action | From | To |
        |---|---|---|
        | `submit_application` | offer | application |
        | `convert_to_policy` | draft, offer, application | policy |
        | `mark_lost` | offer, application | lost |
        | `suspend` | policy | dormant |
        | `reactivate` | dormant | policy |
        | `terminate` | policy, dormant | terminated |
        | `cancel` | policy, dormant | cancelled |
        | `transfer_out` | policy, dormant | transferred_out |
        | `reopen` | terminated, cancelled, transferred_out | policy |
        | `reopen_lost` | lost | offer |

        `convert_to_policy` needs insurer, policy number, gross premium and payment frequency.
        `terminate` needs an `endDate` (body or already on the contract).
      security:
      - ApiKey: []
      - OAuth2:
        - contracts:write
      requestBody:
        required: false
        content:
          application/json:
            schema:
              type: object
              properties:
                endDate:
                  type: string
                  format: date
                  description: Only for `terminate`.
      responses:
        '200':
          description: Status changed.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Contract'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          $ref: '#/components/responses/Conflict'
        '422':
          $ref: '#/components/responses/ValidationFailed'
  /contract-types:
    get:
      tags:
      - Contract catalog
      operationId: listContractTypes
      summary: Contract types and their fields
      description: |
        The schema behind `typeSpecificData`: every contract type with its group, the contact types it
        applies to and its fields (type, options, unit, validation, conditional visibility). Fields with
        `extended: true` are optional detail fields (e.g. the ~90 GDV fields of a vehicle contract).
        Cache the response; it changes only with releases.
      security:
      - ApiKey: []
      - OAuth2:
        - contracts:read
      parameters:
      - name: contactType
        in: query
        description: Only types that apply to this contact type.
        schema:
          $ref: '#/components/schemas/ContactType'
      responses:
        '200':
          description: The catalog.
          content:
            application/json:
              schema:
                type: object
                required:
                - data
                - commonFields
                - paymentFrequencies
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/ContractTypeDefinition'
                  commonFields:
                    type: array
                    description: Fields every contract has (insurer, policyNumber, premium, dates, ...).
                    items:
                      $ref: '#/components/schemas/ContractFieldDefinition'
                  paymentFrequencies:
                    type: array
                    items:
                      $ref: '#/components/schemas/LabeledValue'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /contract-types/{type}:
    parameters:
    - name: type
      in: path
      required: true
      schema:
        $ref: '#/components/schemas/ContractType'
    get:
      tags:
      - Contract catalog
      operationId: getContractType
      summary: One contract type and its fields
      security:
      - ApiKey: []
      - OAuth2:
        - contracts:read
      responses:
        '200':
          description: The contract type.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ContractTypeDefinition'
        '404':
          $ref: '#/components/responses/NotFound'
  /insurers:
    get:
      tags:
      - Contract catalog
      operationId: listInsurers
      summary: Insurer catalog
      description: The shared insurer catalog. Link contracts to an entry via `insurer.insurerId` to get clean reporting and
        correct correspondence routing.
      security:
      - ApiKey: []
      - OAuth2:
        - contracts:read
      parameters:
      - $ref: '#/components/parameters/Search'
      - $ref: '#/components/parameters/Cursor'
      - $ref: '#/components/parameters/Limit'
      responses:
        '200':
          description: A page of insurers.
          content:
            application/json:
              schema:
                type: object
                required:
                - data
                - pagination
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Insurer'
                  pagination:
                    $ref: '#/components/schemas/Pagination'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /insurers/{insurerId}:
    parameters:
    - name: insurerId
      in: path
      required: true
      schema:
        type: string
        format: uuid
    get:
      tags:
      - Contract catalog
      operationId: getInsurer
      summary: Get an insurer
      description: Includes the company's own broker number and notes for this insurer.
      security:
      - ApiKey: []
      - OAuth2:
        - contracts:read
      responses:
        '200':
          description: The insurer.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InsurerDetail'
        '404':
          $ref: '#/components/responses/NotFound'
  /documents:
    get:
      tags:
      - Documents
      operationId: listDocuments
      summary: List documents
      security:
      - ApiKey: []
      - OAuth2:
        - documents:read
      parameters:
      - $ref: '#/components/parameters/Cursor'
      - $ref: '#/components/parameters/Limit'
      - $ref: '#/components/parameters/UpdatedSince'
      - $ref: '#/components/parameters/ContactIdFilter'
      - name: contractId
        in: query
        schema:
          type: string
          format: uuid
      - name: type
        in: query
        description: Comma-separated document types.
        schema:
          type: string
          examples:
          - insurance_policy,policy_amendment
      - name: typeGroup
        in: query
        schema:
          $ref: '#/components/schemas/DocumentTypeGroup'
      - name: source
        in: query
        schema:
          $ref: '#/components/schemas/DocumentSource'
      responses:
        '200':
          description: A page of documents (metadata only).
          content:
            application/json:
              schema:
                type: object
                required:
                - data
                - pagination
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Document'
                  pagination:
                    $ref: '#/components/schemas/Pagination'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
    post:
      tags:
      - Documents
      operationId: uploadDocument
      summary: Upload a document
      description: Multipart upload, up to 100 MB per file. The MIME type is detected from the content.
      security:
      - ApiKey: []
      - OAuth2:
        - documents:write
      parameters:
      - $ref: '#/components/parameters/IdempotencyKey'
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              required:
              - file
              - contactId
              properties:
                file:
                  type: string
                  format: binary
                contactId:
                  type: string
                  format: uuid
                contractId:
                  type: string
                  format: uuid
                type:
                  $ref: '#/components/schemas/DocumentType'
                filename:
                  type: string
                  maxLength: 255
                  description: Overrides the uploaded file name.
                documentDate:
                  type: string
                  format: date
                  description: Date of the document itself, e.g. for archive imports. Defaults to the upload date.
                externalSource:
                  type: string
                  description: 'With `externalId`: your reference for this document.'
                externalId:
                  type: string
                  maxLength: 128
            encoding:
              file:
                contentType: application/pdf, image/*, application/msword, application/vnd.openxmlformats-officedocument.*,
                  text/plain, application/octet-stream
      responses:
        '201':
          description: Uploaded.
          headers:
            Location:
              $ref: '#/components/headers/Location'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Document'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '413':
          description: File larger than 100 MB.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
        '422':
          $ref: '#/components/responses/ValidationFailed'
  /documents/{documentId}:
    parameters:
    - $ref: '#/components/parameters/DocumentId'
    get:
      tags:
      - Documents
      operationId: getDocument
      summary: Get document metadata
      security:
      - ApiKey: []
      - OAuth2:
        - documents:read
      responses:
        '200':
          description: The document.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Document'
        '404':
          $ref: '#/components/responses/NotFound'
    patch:
      tags:
      - Documents
      operationId: updateDocument
      summary: Update document metadata
      description: 'Change type, file name or the linked contract (`contractId: null` unlinks).'
      security:
      - ApiKey: []
      - OAuth2:
        - documents:write
      requestBody:
        required: true
        content:
          application/merge-patch+json:
            schema:
              type: object
              minProperties: 1
              properties:
                type:
                  oneOf:
                  - $ref: '#/components/schemas/DocumentType'
                  - type: 'null'
                filename:
                  type: string
                  maxLength: 255
                contractId:
                  type:
                  - string
                  - 'null'
                  format: uuid
                externalReferences:
                  type: array
                  items:
                    $ref: '#/components/schemas/ExternalReference'
      responses:
        '200':
          description: Updated.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Document'
        '404':
          $ref: '#/components/responses/NotFound'
        '422':
          $ref: '#/components/responses/ValidationFailed'
    delete:
      tags:
      - Documents
      operationId: deleteDocument
      summary: Delete a document
      description: Documents that belong to a signature request cannot be deleted (`409`).
      security:
      - ApiKey: []
      - OAuth2:
        - documents:write
      responses:
        '204':
          description: Deleted.
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          $ref: '#/components/responses/Conflict'
  /documents/{documentId}/content:
    parameters:
    - $ref: '#/components/parameters/DocumentId'
    get:
      tags:
      - Documents
      operationId: downloadDocument
      summary: Download the file
      description: Streams the file. Supports `Range` requests for large files.
      security:
      - ApiKey: []
      - OAuth2:
        - documents:read
      responses:
        '200':
          description: The file.
          headers:
            Content-Disposition:
              schema:
                type: string
                examples:
                - attachment; filename="Police_PHV.pdf"
            Content-Length:
              schema:
                type: integer
          content:
            application/octet-stream:
              schema:
                type: string
                format: binary
        '206':
          description: Partial content.
          content:
            application/octet-stream:
              schema:
                type: string
                format: binary
        '404':
          $ref: '#/components/responses/NotFound'
  /document-types:
    get:
      tags:
      - Documents
      operationId: listDocumentTypes
      summary: Document type catalog
      security:
      - ApiKey: []
      - OAuth2:
        - documents:read
      responses:
        '200':
          description: All document types with their group and labels.
          content:
            application/json:
              schema:
                type: object
                required:
                - data
                properties:
                  data:
                    type: array
                    items:
                      type: object
                      required:
                      - type
                      - label
                      - group
                      - groupLabel
                      properties:
                        type:
                          $ref: '#/components/schemas/DocumentType'
                        label:
                          type: string
                          examples:
                          - Versicherungsschein
                        group:
                          $ref: '#/components/schemas/DocumentTypeGroup'
                        groupLabel:
                          type: string
                          examples:
                          - Versicherungsverträge
        '401':
          $ref: '#/components/responses/Unauthorized'
  /documents/{documentId}/extractions:
    parameters:
    - $ref: '#/components/parameters/DocumentId'
    post:
      tags:
      - Document AI
      operationId: startContractExtraction
      summary: Read contract data from a document
      description: |
        Starts an asynchronous AI extraction that reads common and type-specific contract fields from a
        policy, offer or amendment (PDF, Word, text). Consumes points of the company's plan; failed runs
        are refunded.

        * With `contractId`: the result is compared with that contract (`new`, `match`, `conflict`).
        * Without `contractId`: `contractType` is required. With `autoApply: true` a contract is created
          from the result automatically.

        Poll `GET /extractions/{extractionId}` or listen to `contract.created` / `contract.updated`.
      security:
      - ApiKey: []
      - OAuth2:
        - documents:read
        - contracts:write
      parameters:
      - $ref: '#/components/parameters/IdempotencyKey'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                contractId:
                  type: string
                  format: uuid
                contractType:
                  $ref: '#/components/schemas/ContractType'
                autoApply:
                  type: boolean
                  default: false
                  description: Not combinable with `contractId`.
      responses:
        '202':
          description: Extraction started.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ContractExtraction'
        '402':
          description: Not enough points.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
        '404':
          $ref: '#/components/responses/NotFound'
        '422':
          $ref: '#/components/responses/ValidationFailed'
  /extractions/{extractionId}:
    parameters:
    - name: extractionId
      in: path
      required: true
      schema:
        type: string
        format: uuid
    get:
      tags:
      - Document AI
      operationId: getContractExtraction
      summary: Get an extraction
      security:
      - ApiKey: []
      - OAuth2:
        - documents:read
      responses:
        '200':
          description: Status and, when done, the extracted fields.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ContractExtraction'
        '404':
          $ref: '#/components/responses/NotFound'
  /extractions/{extractionId}/apply:
    parameters:
    - name: extractionId
      in: path
      required: true
      schema:
        type: string
        format: uuid
    post:
      tags:
      - Document AI
      operationId: applyContractExtraction
      summary: Apply extracted fields
      description: Writes the selected fields to the target contract (or creates one). Values can be corrected before applying.
      security:
      - ApiKey: []
      - OAuth2:
        - contracts:write
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - fields
              properties:
                fields:
                  type: array
                  minItems: 1
                  items:
                    type: string
                  examples:
                  - - policyNumber
                    - premium.gross
                    - typeSpecificData.coverageAmount
                values:
                  type: object
                  description: Corrected values keyed like `fields`.
                  additionalProperties:
                    type:
                    - string
                    - number
                    - boolean
                    - 'null'
      responses:
        '200':
          description: Applied.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Contract'
        '409':
          $ref: '#/components/responses/Conflict'
        '422':
          $ref: '#/components/responses/ValidationFailed'
  /correspondence/transaction-types:
    get:
      tags:
      - Insurer correspondence
      operationId: listCorrespondenceTransactionTypes
      summary: Business transactions catalog
      description: |
        What a broker can send to an insurer (address change, cancellation, claim report, ...), with the
        form fields each transaction needs and the contract types it applies to.
      security:
      - ApiKey: []
      - OAuth2:
        - correspondence:read
      responses:
        '200':
          description: The catalog.
          content:
            application/json:
              schema:
                type: object
                required:
                - data
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/CorrespondenceTransactionDefinition'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /correspondence-cases:
    get:
      tags:
      - Insurer correspondence
      operationId: listCorrespondenceCases
      summary: List correspondence cases
      security:
      - ApiKey: []
      - OAuth2:
        - correspondence:read
      parameters:
      - $ref: '#/components/parameters/Cursor'
      - $ref: '#/components/parameters/Limit'
      - $ref: '#/components/parameters/UpdatedSince'
      - $ref: '#/components/parameters/ContactIdFilter'
      - name: contractId
        in: query
        schema:
          type: string
          format: uuid
      - name: status
        in: query
        schema:
          $ref: '#/components/schemas/CorrespondenceStatus'
      responses:
        '200':
          description: A page of cases.
          content:
            application/json:
              schema:
                type: object
                required:
                - data
                - pagination
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/CorrespondenceCase'
                  pagination:
                    $ref: '#/components/schemas/Pagination'
        '401':
          $ref: '#/components/responses/Unauthorized'
    post:
      tags:
      - Insurer correspondence
      operationId: createCorrespondenceCases
      summary: Prepare correspondence
      description: |
        Creates draft cases for one transaction. Contracts of different insurers produce one case per
        insurer. Subject, body and recipient are prefilled from the catalog and the insurer catalog; send
        them with `POST /correspondence-cases/{caseId}/send`.
      security:
      - ApiKey: []
      - OAuth2:
        - correspondence:write
      parameters:
      - $ref: '#/components/parameters/IdempotencyKey'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - contactId
              - contractIds
              - transactionType
              properties:
                contactId:
                  $ref: '#/components/schemas/Uuid'
                contractIds:
                  type: array
                  minItems: 1
                  items:
                    $ref: '#/components/schemas/Uuid'
                transactionType:
                  $ref: '#/components/schemas/CorrespondenceTransactionType'
                formData:
                  type: object
                  description: Values for the transaction's form fields.
                  additionalProperties:
                    type:
                    - string
                    - number
                    - boolean
                    - 'null'
                  examples:
                  - effectiveDate: '2026-11-01'
                    newStreet: Teststraße 200
                    newZipCode: '01069'
                    newCity: Dresden
      responses:
        '201':
          description: Draft cases, one per insurer.
          content:
            application/json:
              schema:
                type: object
                required:
                - data
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/CorrespondenceCase'
        '422':
          $ref: '#/components/responses/ValidationFailed'
  /correspondence-cases/{caseId}:
    parameters:
    - $ref: '#/components/parameters/CorrespondenceCaseId'
    get:
      tags:
      - Insurer correspondence
      operationId: getCorrespondenceCase
      summary: Get a correspondence case
      security:
      - ApiKey: []
      - OAuth2:
        - correspondence:read
      responses:
        '200':
          description: The case.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CorrespondenceCase'
        '404':
          $ref: '#/components/responses/NotFound'
    patch:
      tags:
      - Insurer correspondence
      operationId: updateCorrespondenceCase
      summary: Edit a draft or change the status
      description: '`subject`, `body`, `recipientEmail` and `formData` only while `draft`. `status` only between `sent`, `completed`
        and `follow_up`.'
      security:
      - ApiKey: []
      - OAuth2:
        - correspondence:write
      requestBody:
        required: true
        content:
          application/merge-patch+json:
            schema:
              type: object
              minProperties: 1
              properties:
                subject:
                  type: string
                  maxLength: 500
                body:
                  type: string
                recipientEmail:
                  type: string
                  format: email
                  maxLength: 320
                formData:
                  type: object
                  additionalProperties:
                    type:
                    - string
                    - number
                    - boolean
                    - 'null'
                status:
                  type: string
                  enum:
                  - sent
                  - completed
                  - follow_up
      responses:
        '200':
          description: Updated.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CorrespondenceCase'
        '409':
          $ref: '#/components/responses/Conflict'
        '422':
          $ref: '#/components/responses/ValidationFailed'
    delete:
      tags:
      - Insurer correspondence
      operationId: deleteCorrespondenceCase
      summary: Delete a draft
      security:
      - ApiKey: []
      - OAuth2:
        - correspondence:write
      responses:
        '204':
          description: Deleted.
        '409':
          $ref: '#/components/responses/Conflict'
  /correspondence-cases/{caseId}/send:
    parameters:
    - $ref: '#/components/parameters/CorrespondenceCaseId'
    post:
      tags:
      - Insurer correspondence
      operationId: sendCorrespondenceCase
      summary: Send to the insurer
      description: Sends the case as email from a connected mailbox of the company. The sent email appears in the contact's
        timeline.
      security:
      - ApiKey: []
      - OAuth2:
        - correspondence:write
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - mailboxId
              properties:
                mailboxId:
                  $ref: '#/components/schemas/Uuid'
                recipientEmail:
                  type: string
                  format: email
                  description: Overrides the routed insurer address.
                attachmentDocumentIds:
                  type: array
                  maxItems: 5
                  items:
                    $ref: '#/components/schemas/Uuid'
      responses:
        '200':
          description: Sent.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CorrespondenceCase'
        '409':
          $ref: '#/components/responses/Conflict'
        '422':
          $ref: '#/components/responses/ValidationFailed'
  /mailboxes:
    get:
      tags:
      - Insurer correspondence
      operationId: listMailboxes
      summary: Sending mailboxes
      description: Mailboxes the credential may send from (needed for `send`).
      security:
      - ApiKey: []
      - OAuth2:
        - correspondence:write
      responses:
        '200':
          description: Mailboxes.
          content:
            application/json:
              schema:
                type: object
                required:
                - data
                properties:
                  data:
                    type: array
                    items:
                      type: object
                      required:
                      - id
                      - email
                      - label
                      properties:
                        id:
                          $ref: '#/components/schemas/Uuid'
                        email:
                          type: string
                          format: email
                        label:
                          type: string
                        shared:
                          type: boolean
        '401':
          $ref: '#/components/responses/Unauthorized'
  /signature-requests:
    get:
      tags:
      - E-signature
      operationId: listSignatureRequests
      summary: List signature requests
      security:
      - ApiKey: []
      - OAuth2:
        - signatures:read
      parameters:
      - $ref: '#/components/parameters/Cursor'
      - $ref: '#/components/parameters/Limit'
      - $ref: '#/components/parameters/UpdatedSince'
      - $ref: '#/components/parameters/ContactIdFilter'
      - name: status
        in: query
        schema:
          $ref: '#/components/schemas/SignatureRequestStatus'
      responses:
        '200':
          description: A page of signature requests.
          content:
            application/json:
              schema:
                type: object
                required:
                - data
                - pagination
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/SignatureRequest'
                  pagination:
                    $ref: '#/components/schemas/Pagination'
        '401':
          $ref: '#/components/responses/Unauthorized'
    post:
      tags:
      - E-signature
      operationId: createSignatureRequest
      summary: Send documents for signature
      description: |
        Starts a signing process with the company's e-signature provider (ADV Sign or inSign).
        Documents are contact documents (`documentId`) or company templates (`standardDocumentId`).
        Signature fields are placed from PDF tags or templates; `fields` places them explicitly
        (ADV Sign only, coordinates relative 0–1 to the page).

        Signed documents are stored with the contact automatically (`signedDocumentId`), and
        `signature_request.completed` is sent.
      security:
      - ApiKey: []
      - OAuth2:
        - signatures:write
      parameters:
      - $ref: '#/components/parameters/IdempotencyKey'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SignatureRequestCreate'
      responses:
        '201':
          description: Started.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SignatureRequest'
        '403':
          $ref: '#/components/responses/Forbidden'
        '422':
          $ref: '#/components/responses/ValidationFailed'
  /signature-requests/{signatureRequestId}:
    parameters:
    - $ref: '#/components/parameters/SignatureRequestId'
    get:
      tags:
      - E-signature
      operationId: getSignatureRequest
      summary: Get a signature request
      security:
      - ApiKey: []
      - OAuth2:
        - signatures:read
      responses:
        '200':
          description: The signature request incl. signer progress.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SignatureRequest'
        '404':
          $ref: '#/components/responses/NotFound'
  /signature-requests/{signatureRequestId}/cancel:
    parameters:
    - $ref: '#/components/parameters/SignatureRequestId'
    post:
      tags:
      - E-signature
      operationId: cancelSignatureRequest
      summary: Cancel a signature request
      security:
      - ApiKey: []
      - OAuth2:
        - signatures:write
      responses:
        '200':
          description: Cancelled.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SignatureRequest'
        '409':
          $ref: '#/components/responses/Conflict'
  /signature-requests/{signatureRequestId}/remind:
    parameters:
    - $ref: '#/components/parameters/SignatureRequestId'
    post:
      tags:
      - E-signature
      operationId: remindSignatureRequest
      summary: Remind open signers
      security:
      - ApiKey: []
      - OAuth2:
        - signatures:write
      responses:
        '202':
          description: Reminder queued.
        '409':
          $ref: '#/components/responses/Conflict'
  /standard-documents:
    get:
      tags:
      - E-signature
      operationId: listStandardDocuments
      summary: Company templates for signing
      description: Company-wide PDFs (broker agreement, privacy notice, ...) that can be sent for signature.
      security:
      - ApiKey: []
      - OAuth2:
        - signatures:read
      responses:
        '200':
          description: Templates.
          content:
            application/json:
              schema:
                type: object
                required:
                - data
                properties:
                  data:
                    type: array
                    items:
                      type: object
                      required:
                      - id
                      - name
                      - filename
                      - sizeBytes
                      properties:
                        id:
                          $ref: '#/components/schemas/Uuid'
                        name:
                          type: string
                          examples:
                          - Maklervollmacht
                        filename:
                          type: string
                        sizeBytes:
                          type: integer
                        hasSignatureFields:
                          type: boolean
        '401':
          $ref: '#/components/responses/Unauthorized'
  /leads:
    get:
      tags:
      - Leads
      operationId: listLeads
      summary: List leads
      security:
      - ApiKey: []
      - OAuth2:
        - leads:read
      parameters:
      - $ref: '#/components/parameters/Cursor'
      - $ref: '#/components/parameters/Limit'
      - $ref: '#/components/parameters/UpdatedSince'
      - $ref: '#/components/parameters/Search'
      - name: stageId
        in: query
        schema:
          type: string
          format: uuid
      - name: source
        in: query
        schema:
          $ref: '#/components/schemas/LeadSource'
      - name: ownerId
        in: query
        schema:
          type: string
          format: uuid
      - name: converted
        in: query
        schema:
          type: boolean
      - name: includeTest
        in: query
        description: Include leads submitted in test mode.
        schema:
          type: boolean
          default: false
      responses:
        '200':
          description: A page of leads.
          content:
            application/json:
              schema:
                type: object
                required:
                - data
                - pagination
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Lead'
                  pagination:
                    $ref: '#/components/schemas/Pagination'
        '403':
          $ref: '#/components/responses/Forbidden'
    post:
      tags:
      - Leads
      operationId: createLead
      summary: Create a lead
      description: Server-side lead creation (e.g. from a comparison portal or your own website backend). For browser forms
        use `POST /leads/intake` with a publishable key. Either `email` or `phone` is required.
      security:
      - ApiKey: []
      - OAuth2:
        - leads:write
      parameters:
      - $ref: '#/components/parameters/IdempotencyKey'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/LeadInput'
      responses:
        '201':
          description: Created.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Lead'
        '403':
          $ref: '#/components/responses/Forbidden'
        '422':
          $ref: '#/components/responses/ValidationFailed'
  /leads/intake:
    post:
      tags:
      - Leads
      operationId: intakeLead
      summary: Website lead intake (publishable key)
      description: |
        Browser-safe lead capture for website forms. Authenticate with the publishable key in
        `X-API-Key` (or the `_key` form field). Accepts JSON and `application/x-www-form-urlencoded`
        (`additionalFields.<name>` keys become `additionalFields`). Duplicates are merged according to
        the lead board settings of the key owner.

        Limits: 100 submissions per hour per key. `_redirect` sends a `302` to an allowed domain of the
        key, which lets plain HTML forms work without JavaScript.

        The legacy endpoint `POST /api/public/leads` remains available with the same behaviour.
      security:
      - PublishableKey: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/LeadIntake'
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/LeadIntake'
      responses:
        '201':
          description: Accepted.
          content:
            application/json:
              schema:
                type: object
                required:
                - status
                properties:
                  status:
                    type: string
                    enum:
                    - created
                    - updated
        '302':
          description: Redirect to `_redirect`.
          headers:
            Location:
              schema:
                type: string
                format: uri
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '422':
          $ref: '#/components/responses/ValidationFailed'
        '429':
          $ref: '#/components/responses/TooManyRequests'
  /leads/{leadId}:
    parameters:
    - $ref: '#/components/parameters/LeadId'
    get:
      tags:
      - Leads
      operationId: getLead
      summary: Get a lead
      security:
      - ApiKey: []
      - OAuth2:
        - leads:read
      responses:
        '200':
          description: The lead.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Lead'
        '404':
          $ref: '#/components/responses/NotFound'
    patch:
      tags:
      - Leads
      operationId: updateLead
      summary: Update a lead or move it to another stage
      security:
      - ApiKey: []
      - OAuth2:
        - leads:write
      requestBody:
        required: true
        content:
          application/merge-patch+json:
            schema:
              allOf:
              - $ref: '#/components/schemas/LeadInput'
              - type: object
                properties:
                  stageId:
                    $ref: '#/components/schemas/Uuid'
                  ownerId:
                    type:
                    - string
                    - 'null'
                    format: uuid
      responses:
        '200':
          description: Updated.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Lead'
        '404':
          $ref: '#/components/responses/NotFound'
        '422':
          $ref: '#/components/responses/ValidationFailed'
    delete:
      tags:
      - Leads
      operationId: deleteLead
      summary: Delete a lead
      security:
      - ApiKey: []
      - OAuth2:
        - leads:write
      responses:
        '204':
          description: Deleted.
        '404':
          $ref: '#/components/responses/NotFound'
  /external/{source}/leads/{externalId}:
    parameters:
    - $ref: '#/components/parameters/ExternalSource'
    - $ref: '#/components/parameters/ExternalId'
    put:
      tags:
      - Leads
      operationId: upsertLeadByExternalId
      summary: Create or update a lead by your ID
      security:
      - ApiKey: []
      - OAuth2:
        - leads:write
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/LeadInput'
      responses:
        '200':
          description: Updated.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Lead'
        '201':
          description: Created.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Lead'
        '422':
          $ref: '#/components/responses/ValidationFailed'
  /leads/{leadId}/convert:
    parameters:
    - $ref: '#/components/parameters/LeadId'
    post:
      tags:
      - Leads
      operationId: convertLead
      summary: Convert a lead into a contact
      description: |
        Creates a contact from the lead (or merges it into an existing one), moves the lead's
        attachments to the contact and sets the lead to the final `converted` stage.
        Use `dryRun: true` to get the duplicate candidates and field conflicts first.
      security:
      - ApiKey: []
      - OAuth2:
        - leads:write
        - contacts:write
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - contactType
              properties:
                contactType:
                  $ref: '#/components/schemas/ContactType'
                existingContactId:
                  type: string
                  format: uuid
                  description: Merge into this contact instead of creating a new one.
                overrides:
                  description: Values that win over the lead data, in the shape of `ContactPatch`.
                  allOf:
                  - $ref: '#/components/schemas/ContactPatch'
                dryRun:
                  type: boolean
                  default: false
      responses:
        '200':
          description: Dry run result.
          content:
            application/json:
              schema:
                type: object
                required:
                - duplicates
                - conflicts
                properties:
                  duplicates:
                    type: array
                    items:
                      type: object
                      required:
                      - contact
                      - matchedBy
                      properties:
                        contact:
                          $ref: '#/components/schemas/ContactSummary'
                        matchedBy:
                          type: array
                          items:
                            type: string
                            enum:
                            - email
                            - phone
                  conflicts:
                    type: array
                    items:
                      type: object
                      required:
                      - field
                      - leadValue
                      - contactValue
                      properties:
                        field:
                          type: string
                        leadValue:
                          type:
                          - string
                          - number
                          - boolean
                          - 'null'
                        contactValue:
                          type:
                          - string
                          - number
                          - boolean
                          - 'null'
        '201':
          description: Converted.
          content:
            application/json:
              schema:
                type: object
                required:
                - lead
                - contact
                - linkedExisting
                properties:
                  lead:
                    $ref: '#/components/schemas/Lead'
                  contact:
                    $ref: '#/components/schemas/Contact'
                  linkedExisting:
                    type: boolean
        '409':
          $ref: '#/components/responses/Conflict'
        '422':
          $ref: '#/components/responses/ValidationFailed'
  /leads/{leadId}/attachments/{attachmentId}/content:
    parameters:
    - $ref: '#/components/parameters/LeadId'
    - name: attachmentId
      in: path
      required: true
      schema:
        type: string
        format: uuid
    get:
      tags:
      - Leads
      operationId: downloadLeadAttachment
      summary: Download a lead attachment
      security:
      - ApiKey: []
      - OAuth2:
        - leads:read
      responses:
        '200':
          description: The file.
          content:
            application/octet-stream:
              schema:
                type: string
                format: binary
        '404':
          $ref: '#/components/responses/NotFound'
  /lead-stages:
    get:
      tags:
      - Leads
      operationId: listLeadStages
      summary: Lead pipeline stages
      description: Stages are configured per company. `new` and `converted` always exist.
      security:
      - ApiKey: []
      - OAuth2:
        - leads:read
      responses:
        '200':
          description: Stages in board order.
          content:
            application/json:
              schema:
                type: object
                required:
                - data
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/LeadStage'
        '401':
          $ref: '#/components/responses/Unauthorized'
    post:
      tags:
      - Administration
      operationId: createLeadStage
      summary: Add a stage
      security:
      - ApiKey: []
      - OAuth2:
        - admin:write
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - name
              properties:
                name:
                  type: string
                  maxLength: 100
                color:
                  $ref: '#/components/schemas/LabelColor'
                position:
                  type: integer
                  minimum: 0
                isFinal:
                  type: boolean
                  default: false
      responses:
        '201':
          description: Created.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LeadStage'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /tasks:
    get:
      tags:
      - Tasks
      operationId: listTasks
      summary: List tasks
      security:
      - ApiKey: []
      - OAuth2:
        - tasks:read
      parameters:
      - $ref: '#/components/parameters/Cursor'
      - $ref: '#/components/parameters/Limit'
      - $ref: '#/components/parameters/UpdatedSince'
      - $ref: '#/components/parameters/ContactIdFilter'
      - $ref: '#/components/parameters/AssigneeFilter'
      - name: leadId
        in: query
        schema:
          type: string
          format: uuid
      - name: status
        in: query
        description: Comma-separated statuses.
        schema:
          type: string
          examples:
          - open,in_progress
      - name: priority
        in: query
        schema:
          $ref: '#/components/schemas/TaskPriority'
      - name: dueFrom
        in: query
        schema:
          type: string
          format: date-time
      - name: dueTo
        in: query
        schema:
          type: string
          format: date-time
      responses:
        '200':
          description: A page of tasks.
          content:
            application/json:
              schema:
                type: object
                required:
                - data
                - pagination
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Task'
                  pagination:
                    $ref: '#/components/schemas/Pagination'
        '401':
          $ref: '#/components/responses/Unauthorized'
    post:
      tags:
      - Tasks
      operationId: createTask
      summary: Create a task
      security:
      - ApiKey: []
      - OAuth2:
        - tasks:write
      parameters:
      - $ref: '#/components/parameters/IdempotencyKey'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              allOf:
              - type: object
                required:
                - title
              - $ref: '#/components/schemas/TaskInput'
            example:
              title: Rückruf wegen Kfz-Angebot
              contactId: 01a11123-2e86-713d-9536-4f9a063bab48
              assigneeId: 01a11117-d6dd-73f1-97c4-bb17d975b962
              dueAt: '2026-10-20T10:00:00+02:00'
              priority: high
      responses:
        '201':
          description: Created.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Task'
        '422':
          $ref: '#/components/responses/ValidationFailed'
  /tasks/{taskId}:
    parameters:
    - $ref: '#/components/parameters/TaskId'
    get:
      tags:
      - Tasks
      operationId: getTask
      summary: Get a task
      security:
      - ApiKey: []
      - OAuth2:
        - tasks:read
      responses:
        '200':
          description: The task.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Task'
        '404':
          $ref: '#/components/responses/NotFound'
    patch:
      tags:
      - Tasks
      operationId: updateTask
      summary: Update a task
      description: 'Set `status: done` to complete it (emits `task.completed`).'
      security:
      - ApiKey: []
      - OAuth2:
        - tasks:write
      requestBody:
        required: true
        content:
          application/merge-patch+json:
            schema:
              $ref: '#/components/schemas/TaskInput'
      responses:
        '200':
          description: Updated.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Task'
        '404':
          $ref: '#/components/responses/NotFound'
        '422':
          $ref: '#/components/responses/ValidationFailed'
    delete:
      tags:
      - Tasks
      operationId: deleteTask
      summary: Delete a task
      security:
      - ApiKey: []
      - OAuth2:
        - tasks:write
      responses:
        '204':
          description: Deleted.
        '404':
          $ref: '#/components/responses/NotFound'
  /tasks/{taskId}/comments:
    parameters:
    - $ref: '#/components/parameters/TaskId'
    get:
      tags:
      - Tasks
      operationId: listTaskComments
      summary: Task comments
      security:
      - ApiKey: []
      - OAuth2:
        - tasks:read
      parameters:
      - $ref: '#/components/parameters/Cursor'
      - $ref: '#/components/parameters/Limit'
      responses:
        '200':
          description: A page of comments, oldest first.
          content:
            application/json:
              schema:
                type: object
                required:
                - data
                - pagination
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/TaskComment'
                  pagination:
                    $ref: '#/components/schemas/Pagination'
        '401':
          $ref: '#/components/responses/Unauthorized'
    post:
      tags:
      - Tasks
      operationId: createTaskComment
      summary: Comment on a task
      security:
      - ApiKey: []
      - OAuth2:
        - tasks:write
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - content
              properties:
                content:
                  type: string
                  maxLength: 10000
                parentCommentId:
                  $ref: '#/components/schemas/Uuid'
      responses:
        '201':
          description: Added.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TaskComment'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /appointments:
    get:
      tags:
      - Appointments
      operationId: listAppointments
      summary: List appointments in a time range
      description: Recurring appointments are expanded into occurrences within `from`–`to` (max. 366 days).
      security:
      - ApiKey: []
      - OAuth2:
        - appointments:read
      parameters:
      - name: from
        in: query
        required: true
        schema:
          type: string
          format: date-time
      - name: to
        in: query
        required: true
        schema:
          type: string
          format: date-time
      - $ref: '#/components/parameters/ContactIdFilter'
      - name: ownerId
        in: query
        schema:
          type: string
          format: uuid
      - name: type
        in: query
        schema:
          $ref: '#/components/schemas/AppointmentType'
      responses:
        '200':
          description: Occurrences in the range, ordered by start.
          content:
            application/json:
              schema:
                type: object
                required:
                - data
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Appointment'
        '401':
          $ref: '#/components/responses/Unauthorized'
    post:
      tags:
      - Appointments
      operationId: createAppointment
      summary: Create an appointment
      security:
      - ApiKey: []
      - OAuth2:
        - appointments:write
      parameters:
      - $ref: '#/components/parameters/IdempotencyKey'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              allOf:
              - type: object
                required:
                - title
                - startAt
                - endAt
              - $ref: '#/components/schemas/AppointmentInput'
      responses:
        '201':
          description: Created.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Appointment'
        '422':
          $ref: '#/components/responses/ValidationFailed'
  /appointments/{appointmentId}:
    parameters:
    - name: appointmentId
      in: path
      required: true
      schema:
        type: string
        format: uuid
    - name: scope
      in: query
      description: 'For recurring appointments: which occurrences a change or deletion affects.'
      schema:
        type: string
        enum:
        - this
        - following
        - all
        default: all
    - name: occurrenceStart
      in: query
      description: Start of the occurrence, required with `scope=this` or `following`.
      schema:
        type: string
        format: date-time
    get:
      tags:
      - Appointments
      operationId: getAppointment
      summary: Get an appointment
      security:
      - ApiKey: []
      - OAuth2:
        - appointments:read
      responses:
        '200':
          description: The appointment (series master for recurring ones).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Appointment'
        '404':
          $ref: '#/components/responses/NotFound'
    patch:
      tags:
      - Appointments
      operationId: updateAppointment
      summary: Update an appointment
      security:
      - ApiKey: []
      - OAuth2:
        - appointments:write
      requestBody:
        required: true
        content:
          application/merge-patch+json:
            schema:
              $ref: '#/components/schemas/AppointmentInput'
      responses:
        '200':
          description: Updated.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Appointment'
        '404':
          $ref: '#/components/responses/NotFound'
        '422':
          $ref: '#/components/responses/ValidationFailed'
    delete:
      tags:
      - Appointments
      operationId: deleteAppointment
      summary: Delete an appointment
      security:
      - ApiKey: []
      - OAuth2:
        - appointments:write
      responses:
        '204':
          description: Deleted.
        '404':
          $ref: '#/components/responses/NotFound'
  /offer-processes:
    get:
      tags:
      - Offers
      operationId: listOfferProcesses
      summary: Comparison and offer processes
      description: Offers and applications started from Advision360 through connected comparison platforms (F&B, Mr-Money,
        NAFI, BiPRO). Read-only.
      security:
      - ApiKey: []
      - OAuth2:
        - contracts:read
      parameters:
      - $ref: '#/components/parameters/Cursor'
      - $ref: '#/components/parameters/Limit'
      - $ref: '#/components/parameters/UpdatedSince'
      - $ref: '#/components/parameters/ContactIdFilter'
      - name: status
        in: query
        schema:
          $ref: '#/components/schemas/OfferProcessStatus'
      responses:
        '200':
          description: A page of offer processes.
          content:
            application/json:
              schema:
                type: object
                required:
                - data
                - pagination
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/OfferProcess'
                  pagination:
                    $ref: '#/components/schemas/Pagination'
        '401':
          $ref: '#/components/responses/Unauthorized'
    post:
      tags:
      - Offers
      operationId: startOfferProcess
      summary: Start a comparison
      description: |
        Starts a comparison at a connected platform with the contact's data and returns the URL to
        continue there. Results, offers and applications flow back automatically and create contracts
        with status `offer` or `application`.
      security:
      - ApiKey: []
      - OAuth2:
        - offers:write
      parameters:
      - $ref: '#/components/parameters/IdempotencyKey'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - provider
              - line
              - contactId
              properties:
                provider:
                  type: string
                  enum:
                  - fnb
                  - mrmoney
                  - nafi
                  - bipro_stuttgarter
                line:
                  type: string
                  enum:
                  - kfz
                  - household
                  - personalLiability
                  - legalProtection
                  - accident
                  - building
                  - petLiability
                  - petHealthDog
                  - petHealthHorse
                  - petHealthCat
                  - propertyOwnerLiability
                  - waterDamageLiability
                  - photovoltaic
                  - bicycle
                  - construction
                  - health
                  - healthAdditional
                  - retirement
                  - occupationalDisability
                  - workDisability
                  - termLife
                  - childrenProducts
                contactId:
                  $ref: '#/components/schemas/Uuid'
                replacesContractId:
                  $ref: '#/components/schemas/Uuid'
                input:
                  type: object
                  description: Additional comparison input, e.g. vehicle data for `kfz`.
                  additionalProperties: true
      responses:
        '201':
          description: Started.
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/OfferProcess'
                - type: object
                  required:
                  - accessUrl
                  properties:
                    accessUrl:
                      type: string
                      format: uri
        '403':
          $ref: '#/components/responses/Forbidden'
        '422':
          $ref: '#/components/responses/ValidationFailed'
  /integrations/providers:
    get:
      tags:
      - AMS connections
      operationId: listIntegrationProviders
      summary: Supported AMS, pools and platforms
      description: |
        Catalog of the systems Advision360 exchanges data with: agency management systems (AMS /
        Maklerverwaltungsprogramme), broker pools, comparison platforms, insurer interfaces and document
        services. `standards` lists the protocols a provider speaks, `capabilities` what can be synced.

        Systems that are not in the catalog connect through the standard interfaces:
        `gdv_vu_vermittler` files (see Portfolio transfer), BiPRO deliveries or this REST API.
      security:
      - ApiKey: []
      - OAuth2:
        - integrations:read
      parameters:
      - name: category
        in: query
        schema:
          $ref: '#/components/schemas/IntegrationCategory'
      responses:
        '200':
          description: The catalog.
          content:
            application/json:
              schema:
                type: object
                required:
                - data
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/IntegrationProvider'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /integrations/connections:
    get:
      tags:
      - AMS connections
      operationId: listIntegrationConnections
      summary: Connected systems
      security:
      - ApiKey: []
      - OAuth2:
        - integrations:read
      parameters:
      - name: provider
        in: query
        schema:
          type: string
          examples:
          - professional_works
      - name: status
        in: query
        schema:
          $ref: '#/components/schemas/IntegrationConnectionStatus'
      responses:
        '200':
          description: Connections of the company.
          content:
            application/json:
              schema:
                type: object
                required:
                - data
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/IntegrationConnection'
        '401':
          $ref: '#/components/responses/Unauthorized'
    post:
      tags:
      - AMS connections
      operationId: createIntegrationConnection
      summary: Connect a system
      description: |
        Creates a connection. Providers with OAuth return an `authorizationUrl` that a user of the company
        has to open once (`status: pending_authorization`); credential-based providers are verified
        immediately.
      security:
      - ApiKey: []
      - OAuth2:
        - integrations:write
      parameters:
      - $ref: '#/components/parameters/IdempotencyKey'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - provider
              properties:
                provider:
                  type: string
                  examples:
                  - professional_works
                ownerId:
                  type: string
                  format: uuid
                  description: User whose portfolio the connection syncs. Defaults to the acting user.
                environment:
                  type: string
                  enum:
                  - production
                  - test
                  default: production
                credentials:
                  type: object
                  description: Provider-specific, e.g. `username`/`password`, `apiKey` or a BiPRO certificate reference.
                  additionalProperties:
                    type: string
                settings:
                  $ref: '#/components/schemas/IntegrationSettings'
      responses:
        '201':
          description: Created.
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/IntegrationConnection'
                - type: object
                  properties:
                    authorizationUrl:
                      type:
                      - string
                      - 'null'
                      format: uri
        '409':
          $ref: '#/components/responses/Conflict'
        '422':
          $ref: '#/components/responses/ValidationFailed'
  /integrations/connections/{connectionId}:
    parameters:
    - $ref: '#/components/parameters/ConnectionId'
    get:
      tags:
      - AMS connections
      operationId: getIntegrationConnection
      summary: Get a connection
      security:
      - ApiKey: []
      - OAuth2:
        - integrations:read
      responses:
        '200':
          description: The connection.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IntegrationConnection'
        '404':
          $ref: '#/components/responses/NotFound'
    patch:
      tags:
      - AMS connections
      operationId: updateIntegrationConnection
      summary: Change sync settings
      security:
      - ApiKey: []
      - OAuth2:
        - integrations:write
      requestBody:
        required: true
        content:
          application/merge-patch+json:
            schema:
              type: object
              properties:
                enabled:
                  type: boolean
                isPrimary:
                  type: boolean
                  description: Contacts created in Advision360 are pushed to the primary system.
                settings:
                  $ref: '#/components/schemas/IntegrationSettings'
      responses:
        '200':
          description: Updated.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IntegrationConnection'
        '404':
          $ref: '#/components/responses/NotFound'
    delete:
      tags:
      - AMS connections
      operationId: deleteIntegrationConnection
      summary: Disconnect a system
      description: '`purgeImportedData=true` also removes the contacts and contracts this connection imported.'
      security:
      - ApiKey: []
      - OAuth2:
        - integrations:write
      parameters:
      - name: purgeImportedData
        in: query
        schema:
          type: boolean
          default: false
      responses:
        '202':
          description: Disconnected; purge runs in the background.
        '404':
          $ref: '#/components/responses/NotFound'
  /integrations/connections/{connectionId}/sync:
    parameters:
    - $ref: '#/components/parameters/ConnectionId'
    post:
      tags:
      - AMS connections
      operationId: startIntegrationSync
      summary: Start a sync run
      description: Runs are queued per company; only one run is active at a time. Progress is reported via `integration.sync_*`
        events.
      security:
      - ApiKey: []
      - OAuth2:
        - integrations:write
      requestBody:
        required: false
        content:
          application/json:
            schema:
              type: object
              properties:
                mode:
                  type: string
                  enum:
                  - incremental
                  - full
                  default: incremental
                scopes:
                  type: array
                  items:
                    $ref: '#/components/schemas/SyncScope'
      responses:
        '202':
          description: Queued.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SyncRun'
        '409':
          $ref: '#/components/responses/Conflict'
  /integrations/connections/{connectionId}/field-mappings:
    parameters:
    - $ref: '#/components/parameters/ConnectionId'
    get:
      tags:
      - AMS connections
      operationId: getFieldMappings
      summary: Field mapping of a connection
      description: How fields of the external system map to Advision360 contact and contract fields.
      security:
      - ApiKey: []
      - OAuth2:
        - integrations:read
      responses:
        '200':
          description: Mapping rules.
          content:
            application/json:
              schema:
                type: object
                required:
                - data
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/FieldMapping'
        '401':
          $ref: '#/components/responses/Unauthorized'
    put:
      tags:
      - AMS connections
      operationId: replaceFieldMappings
      summary: Replace the field mapping
      security:
      - ApiKey: []
      - OAuth2:
        - integrations:write
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - data
              properties:
                data:
                  type: array
                  items:
                    $ref: '#/components/schemas/FieldMapping'
      responses:
        '200':
          description: Saved.
          content:
            application/json:
              schema:
                type: object
                required:
                - data
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/FieldMapping'
        '422':
          $ref: '#/components/responses/ValidationFailed'
  /integrations/sync-runs:
    get:
      tags:
      - AMS connections
      operationId: listSyncRuns
      summary: Sync history
      security:
      - ApiKey: []
      - OAuth2:
        - integrations:read
      parameters:
      - $ref: '#/components/parameters/Cursor'
      - $ref: '#/components/parameters/Limit'
      - name: connectionId
        in: query
        schema:
          type: string
          format: uuid
      - name: status
        in: query
        schema:
          $ref: '#/components/schemas/SyncRunStatus'
      responses:
        '200':
          description: A page of runs, newest first.
          content:
            application/json:
              schema:
                type: object
                required:
                - data
                - pagination
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/SyncRun'
                  pagination:
                    $ref: '#/components/schemas/Pagination'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /integrations/sync-runs/{runId}:
    parameters:
    - $ref: '#/components/parameters/SyncRunId'
    get:
      tags:
      - AMS connections
      operationId: getSyncRun
      summary: Get a sync run
      security:
      - ApiKey: []
      - OAuth2:
        - integrations:read
      responses:
        '200':
          description: The run with counters per object type.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SyncRun'
        '404':
          $ref: '#/components/responses/NotFound'
  /integrations/sync-runs/{runId}/cancel:
    parameters:
    - $ref: '#/components/parameters/SyncRunId'
    post:
      tags:
      - AMS connections
      operationId: cancelSyncRun
      summary: Cancel a sync run
      security:
      - ApiKey: []
      - OAuth2:
        - integrations:write
      responses:
        '202':
          description: Cancellation requested; the current page finishes first.
        '409':
          $ref: '#/components/responses/Conflict'
  /integrations/sync-runs/{runId}/issues:
    parameters:
    - $ref: '#/components/parameters/SyncRunId'
    get:
      tags:
      - AMS connections
      operationId: listSyncRunIssues
      summary: Records that could not be synced
      security:
      - ApiKey: []
      - OAuth2:
        - integrations:read
      parameters:
      - $ref: '#/components/parameters/Cursor'
      - $ref: '#/components/parameters/Limit'
      - name: severity
        in: query
        schema:
          type: string
          enum:
          - warning
          - error
      responses:
        '200':
          description: A page of issues.
          content:
            application/json:
              schema:
                type: object
                required:
                - data
                - pagination
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/SyncIssue'
                  pagination:
                    $ref: '#/components/schemas/Pagination'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /portfolio-transfers:
    get:
      tags:
      - Portfolio transfer
      operationId: listPortfolioTransfers
      summary: Portfolio imports
      security:
      - ApiKey: []
      - OAuth2:
        - portfolio:read
      parameters:
      - $ref: '#/components/parameters/Cursor'
      - $ref: '#/components/parameters/Limit'
      - name: status
        in: query
        schema:
          $ref: '#/components/schemas/PortfolioTransferStatus'
      responses:
        '200':
          description: A page of transfers.
          content:
            application/json:
              schema:
                type: object
                required:
                - data
                - pagination
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/PortfolioTransfer'
                  pagination:
                    $ref: '#/components/schemas/Pagination'
        '401':
          $ref: '#/components/responses/Unauthorized'
    post:
      tags:
      - Portfolio transfer
      operationId: createPortfolioTransfer
      summary: Import a portfolio file
      description: |
        Imports contacts and contracts from an AMS or insurer export. Supported formats:

        | Format | Content |
        |---|---|
        | `gdv_vu_vermittler` | GDV-Datensatz VU-Vermittler (fixed-width, ISO-8859-15), record types 0001 Vorsatz, 0100 Adressteil, 0200 Allgemeiner Vertragsteil, 0210/0220 spartenspezifische Teile, 0230 Fondsdaten, 0300 Bezugsrechte, 0400 Inkasso, 0500 Schaden, 9999 Nachsatz |
        | `bipro_430_4` | BiPRO 430.4 contract data (XML) |
        | `csv` | Semicolon-separated export with a field mapping (`mappingId`) |

        The file is validated first (`status: validated`, see `summary` and `issues`). With
        `autoCommit: false` nothing is written until `POST /portfolio-transfers/{transferId}/commit`.
        Contacts and contracts are matched by external reference, then policy number + insurer, then
        name + date of birth.
      security:
      - ApiKey: []
      - OAuth2:
        - portfolio:write
      parameters:
      - $ref: '#/components/parameters/IdempotencyKey'
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              required:
              - file
              - format
              properties:
                file:
                  type: string
                  format: binary
                format:
                  $ref: '#/components/schemas/PortfolioFormat'
                source:
                  type: string
                  description: Source key for the external references, e.g. `my-ams`.
                  examples:
                  - my-ams
                ownerId:
                  type: string
                  format: uuid
                mappingId:
                  type: string
                  format: uuid
                  description: Required for `csv`.
                autoCommit:
                  type: boolean
                  default: false
                writeMode:
                  $ref: '#/components/schemas/WriteMode'
      responses:
        '202':
          description: Accepted, validation runs in the background.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PortfolioTransfer'
        '413':
          description: File larger than 500 MB.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
        '422':
          $ref: '#/components/responses/ValidationFailed'
  /portfolio-transfers/{transferId}:
    parameters:
    - $ref: '#/components/parameters/PortfolioTransferId'
    get:
      tags:
      - Portfolio transfer
      operationId: getPortfolioTransfer
      summary: Status and summary of an import
      security:
      - ApiKey: []
      - OAuth2:
        - portfolio:read
      responses:
        '200':
          description: The transfer.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PortfolioTransfer'
        '404':
          $ref: '#/components/responses/NotFound'
    delete:
      tags:
      - Portfolio transfer
      operationId: discardPortfolioTransfer
      summary: Discard an uncommitted import
      security:
      - ApiKey: []
      - OAuth2:
        - portfolio:write
      responses:
        '204':
          description: Discarded.
        '409':
          $ref: '#/components/responses/Conflict'
  /portfolio-transfers/{transferId}/commit:
    parameters:
    - $ref: '#/components/parameters/PortfolioTransferId'
    post:
      tags:
      - Portfolio transfer
      operationId: commitPortfolioTransfer
      summary: Apply a validated import
      security:
      - ApiKey: []
      - OAuth2:
        - portfolio:write
      requestBody:
        required: false
        content:
          application/json:
            schema:
              type: object
              properties:
                skipRecordsWithErrors:
                  type: boolean
                  default: true
      responses:
        '202':
          description: Import started.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PortfolioTransfer'
        '409':
          $ref: '#/components/responses/Conflict'
  /portfolio-transfers/{transferId}/issues:
    parameters:
    - $ref: '#/components/parameters/PortfolioTransferId'
    get:
      tags:
      - Portfolio transfer
      operationId: listPortfolioTransferIssues
      summary: Validation issues of an import
      security:
      - ApiKey: []
      - OAuth2:
        - portfolio:read
      parameters:
      - $ref: '#/components/parameters/Cursor'
      - $ref: '#/components/parameters/Limit'
      responses:
        '200':
          description: A page of issues with line and record type.
          content:
            application/json:
              schema:
                type: object
                required:
                - data
                - pagination
                properties:
                  data:
                    type: array
                    items:
                      allOf:
                      - $ref: '#/components/schemas/SyncIssue'
                      - type: object
                        properties:
                          line:
                            type: integer
                          recordType:
                            type: string
                            examples:
                            - '0200'
                  pagination:
                    $ref: '#/components/schemas/Pagination'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /portfolio-transfers/gdv/line-mappings:
    get:
      tags:
      - Portfolio transfer
      operationId: listGdvLineMappings
      summary: GDV line of business to contract type
      description: How GDV Sparten are mapped to Advision360 contract types during import and export. Company-specific overrides
        are included.
      security:
      - ApiKey: []
      - OAuth2:
        - portfolio:read
      responses:
        '200':
          description: The mapping.
          content:
            application/json:
              schema:
                type: object
                required:
                - data
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/GdvLineMapping'
        '401':
          $ref: '#/components/responses/Unauthorized'
    put:
      tags:
      - Portfolio transfer
      operationId: replaceGdvLineMappings
      summary: Override the GDV mapping
      security:
      - ApiKey: []
      - OAuth2:
        - portfolio:write
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - data
              properties:
                data:
                  type: array
                  items:
                    $ref: '#/components/schemas/GdvLineMapping'
      responses:
        '200':
          description: Saved.
          content:
            application/json:
              schema:
                type: object
                required:
                - data
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/GdvLineMapping'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /exports:
    get:
      tags:
      - Portfolio transfer
      operationId: listExports
      summary: Export jobs
      security:
      - ApiKey: []
      - OAuth2:
        - exports:write
      parameters:
      - $ref: '#/components/parameters/Cursor'
      - $ref: '#/components/parameters/Limit'
      responses:
        '200':
          description: A page of exports.
          content:
            application/json:
              schema:
                type: object
                required:
                - data
                - pagination
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/ExportJob'
                  pagination:
                    $ref: '#/components/schemas/Pagination'
        '401':
          $ref: '#/components/responses/Unauthorized'
    post:
      tags:
      - Portfolio transfer
      operationId: createExport
      summary: Export portfolio data
      description: |
        Exports contacts, contracts or both, e.g. to hand a portfolio over to an AMS. `gdv_vu_vermittler`
        produces a GDV file with record types 0001, 0100, 0200, 0210, 0220 and 9999. The download link is
        valid for 24 hours.
      security:
      - ApiKey: []
      - OAuth2:
        - exports:write
      parameters:
      - $ref: '#/components/parameters/IdempotencyKey'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - format
              - objects
              properties:
                format:
                  type: string
                  enum:
                  - gdv_vu_vermittler
                  - bipro_430_4
                  - csv
                  - xlsx
                  - json
                objects:
                  type: array
                  minItems: 1
                  items:
                    type: string
                    enum:
                    - contacts
                    - contracts
                    - leads
                    - documents_index
                    - claims
                    - commission_entries
                filters:
                  type: object
                  properties:
                    ownerId:
                      type: string
                      format: uuid
                    contactIds:
                      type: array
                      items:
                        $ref: '#/components/schemas/Uuid'
                    contractTypes:
                      type: array
                      items:
                        $ref: '#/components/schemas/ContractType'
                    updatedSince:
                      type: string
                      format: date-time
                includeDocuments:
                  type: boolean
                  default: false
                  description: Adds a ZIP with the documents.
      responses:
        '202':
          description: Export queued.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ExportJob'
        '422':
          $ref: '#/components/responses/ValidationFailed'
  /exports/{exportId}:
    parameters:
    - name: exportId
      in: path
      required: true
      schema:
        type: string
        format: uuid
    get:
      tags:
      - Portfolio transfer
      operationId: getExport
      summary: Get an export job
      security:
      - ApiKey: []
      - OAuth2:
        - exports:write
      responses:
        '200':
          description: The export with `downloadUrl` once completed.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ExportJob'
        '404':
          $ref: '#/components/responses/NotFound'
  /bipro/deliveries:
    get:
      tags:
      - BiPRO
      operationId: listBiproDeliveries
      summary: BiPRO deliveries from insurers
      description: |
        Deliveries fetched through the BiPRO 430 transfer services of connected insurers: contract
        documents, portfolio changes, collections, claims and commission statements. Each delivery is
        matched to a contact and contract where possible.
      security:
      - ApiKey: []
      - OAuth2:
        - portfolio:read
      parameters:
      - $ref: '#/components/parameters/Cursor'
      - $ref: '#/components/parameters/Limit'
      - $ref: '#/components/parameters/UpdatedSince'
      - name: insurerId
        in: query
        schema:
          type: string
          format: uuid
      - name: category
        in: query
        schema:
          $ref: '#/components/schemas/BiproCategory'
      - name: status
        in: query
        schema:
          $ref: '#/components/schemas/BiproDeliveryStatus'
      - $ref: '#/components/parameters/ContactIdFilter'
      responses:
        '200':
          description: A page of deliveries.
          content:
            application/json:
              schema:
                type: object
                required:
                - data
                - pagination
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/BiproDelivery'
                  pagination:
                    $ref: '#/components/schemas/Pagination'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /bipro/deliveries/{deliveryId}:
    parameters:
    - $ref: '#/components/parameters/BiproDeliveryId'
    get:
      tags:
      - BiPRO
      operationId: getBiproDelivery
      summary: Get a delivery
      security:
      - ApiKey: []
      - OAuth2:
        - portfolio:read
      responses:
        '200':
          description: The delivery with its documents and data records.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BiproDelivery'
        '404':
          $ref: '#/components/responses/NotFound'
  /bipro/deliveries/{deliveryId}/assign:
    parameters:
    - $ref: '#/components/parameters/BiproDeliveryId'
    post:
      tags:
      - BiPRO
      operationId: assignBiproDelivery
      summary: Assign an unmatched delivery
      security:
      - ApiKey: []
      - OAuth2:
        - portfolio:write
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - contactId
              properties:
                contactId:
                  $ref: '#/components/schemas/Uuid'
                contractId:
                  $ref: '#/components/schemas/Uuid'
      responses:
        '200':
          description: Assigned; documents are filed with the contact.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BiproDelivery'
        '404':
          $ref: '#/components/responses/NotFound'
  /bipro/deliveries/{deliveryId}/acknowledge:
    parameters:
    - $ref: '#/components/parameters/BiproDeliveryId'
    post:
      tags:
      - BiPRO
      operationId: acknowledgeBiproDelivery
      summary: Mark a delivery as processed
      description: Sends the BiPRO acknowledgement (Quittung) to the insurer.
      security:
      - ApiKey: []
      - OAuth2:
        - portfolio:write
      responses:
        '200':
          description: Acknowledged.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BiproDelivery'
        '409':
          $ref: '#/components/responses/Conflict'
  /bipro/insurers:
    get:
      tags:
      - BiPRO
      operationId: listBiproInsurers
      summary: Insurers with BiPRO access
      security:
      - ApiKey: []
      - OAuth2:
        - portfolio:read
      responses:
        '200':
          description: Insurers and the BiPRO norms available for the company.
          content:
            application/json:
              schema:
                type: object
                required:
                - data
                properties:
                  data:
                    type: array
                    items:
                      type: object
                      required:
                      - insurer
                      - norms
                      - status
                      properties:
                        insurer:
                          $ref: '#/components/schemas/Insurer'
                        norms:
                          type: array
                          items:
                            type: string
                            enum:
                            - '410'
                            - '420'
                            - '430.1'
                            - '430.2'
                            - '430.4'
                            - '430.5'
                            - '440'
                        status:
                          type: string
                          enum:
                          - active
                          - credentials_missing
                          - error
                        lastFetchAt:
                          type:
                          - string
                          - 'null'
                          format: date-time
        '401':
          $ref: '#/components/responses/Unauthorized'
  /external-references:
    get:
      tags:
      - Sync protocol
      operationId: listExternalReferences
      summary: ID mapping of a source system
      description: All Advision360 IDs mapped to IDs of one source, e.g. to rebuild the mapping table of an AMS connector.
      security:
      - ApiKey: []
      - OAuth2:
        - contacts:read
      parameters:
      - name: source
        in: query
        required: true
        schema:
          type: string
          pattern: ^[a-z0-9][a-z0-9-]{1,63}$
      - name: objectType
        in: query
        schema:
          $ref: '#/components/schemas/SyncObjectType'
      - $ref: '#/components/parameters/Cursor'
      - $ref: '#/components/parameters/Limit'
      responses:
        '200':
          description: A page of mappings.
          content:
            application/json:
              schema:
                type: object
                required:
                - data
                - pagination
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/ExternalReferenceMapping'
                  pagination:
                    $ref: '#/components/schemas/Pagination'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /external-references/resolve:
    post:
      tags:
      - Sync protocol
      operationId: resolveExternalReferences
      summary: Resolve up to 500 external IDs
      security:
      - ApiKey: []
      - OAuth2:
        - contacts:read
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - source
              - objectType
              - externalIds
              properties:
                source:
                  type: string
                objectType:
                  $ref: '#/components/schemas/SyncObjectType'
                externalIds:
                  type: array
                  maxItems: 500
                  items:
                    type: string
      responses:
        '200':
          description: Found mappings; unknown IDs are listed in `missing`.
          content:
            application/json:
              schema:
                type: object
                required:
                - data
                - missing
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/ExternalReferenceMapping'
                  missing:
                    type: array
                    items:
                      type: string
        '401':
          $ref: '#/components/responses/Unauthorized'
  /sync/checkpoints/{source}:
    parameters:
    - name: source
      in: path
      required: true
      schema:
        type: string
        pattern: ^[a-z0-9][a-z0-9-]{1,63}$
    get:
      tags:
      - Sync protocol
      operationId: getSyncCheckpoint
      summary: Read a sync checkpoint
      description: Lets a connector store where it stopped (event cursor, timestamps), so it can resume from any machine.
      security:
      - ApiKey: []
      - OAuth2:
        - events:read
      responses:
        '200':
          description: The checkpoint.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SyncCheckpoint'
        '404':
          $ref: '#/components/responses/NotFound'
    put:
      tags:
      - Sync protocol
      operationId: saveSyncCheckpoint
      summary: Save a sync checkpoint
      security:
      - ApiKey: []
      - OAuth2:
        - events:read
      parameters:
      - $ref: '#/components/parameters/IfMatch'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SyncCheckpoint'
      responses:
        '200':
          description: Saved.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SyncCheckpoint'
        '412':
          $ref: '#/components/responses/PreconditionFailed'
  /claims:
    get:
      tags:
      - Claims
      operationId: listClaims
      summary: List claims
      security:
      - ApiKey: []
      - OAuth2:
        - claims:read
      parameters:
      - $ref: '#/components/parameters/Cursor'
      - $ref: '#/components/parameters/Limit'
      - $ref: '#/components/parameters/UpdatedSince'
      - $ref: '#/components/parameters/ContactIdFilter'
      - name: contractId
        in: query
        schema:
          type: string
          format: uuid
      - name: status
        in: query
        description: Comma-separated statuses.
        schema:
          type: string
      - name: type
        in: query
        schema:
          $ref: '#/components/schemas/ClaimType'
      - name: dateOfLossFrom
        in: query
        schema:
          type: string
          format: date
      - name: dateOfLossTo
        in: query
        schema:
          type: string
          format: date
      responses:
        '200':
          description: A page of claims.
          content:
            application/json:
              schema:
                type: object
                required:
                - data
                - pagination
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Claim'
                  pagination:
                    $ref: '#/components/schemas/Pagination'
        '401':
          $ref: '#/components/responses/Unauthorized'
    post:
      tags:
      - Claims
      operationId: createClaim
      summary: Record a claim
      security:
      - ApiKey: []
      - OAuth2:
        - claims:write
      parameters:
      - $ref: '#/components/parameters/IdempotencyKey'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              allOf:
              - type: object
                required:
                - contractId
                - dateOfLoss
                - type
              - $ref: '#/components/schemas/ClaimInput'
            example:
              contractId: 01a11123-3411-7f56-830d-bd65a5100449
              type: liability
              dateOfLoss: '2026-10-11'
              description: Beim Umzug wurde der Laminatboden in der Mietwohnung beschädigt.
              location:
                street: Teststraße
                houseNumber: '200'
                zipCode: '01069'
                city: Dresden
                country: DE
              estimatedAmount: '1850.00'
      responses:
        '201':
          description: Recorded.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Claim'
        '422':
          $ref: '#/components/responses/ValidationFailed'
  /claims/{claimId}:
    parameters:
    - $ref: '#/components/parameters/ClaimId'
    get:
      tags:
      - Claims
      operationId: getClaim
      summary: Get a claim
      security:
      - ApiKey: []
      - OAuth2:
        - claims:read
      responses:
        '200':
          description: The claim.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Claim'
        '404':
          $ref: '#/components/responses/NotFound'
    patch:
      tags:
      - Claims
      operationId: updateClaim
      summary: Update a claim
      security:
      - ApiKey: []
      - OAuth2:
        - claims:write
      requestBody:
        required: true
        content:
          application/merge-patch+json:
            schema:
              $ref: '#/components/schemas/ClaimInput'
      responses:
        '200':
          description: Updated.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Claim'
        '404':
          $ref: '#/components/responses/NotFound'
        '422':
          $ref: '#/components/responses/ValidationFailed'
    delete:
      tags:
      - Claims
      operationId: deleteClaim
      summary: Delete a claim
      security:
      - ApiKey: []
      - OAuth2:
        - claims:write
      responses:
        '204':
          description: Deleted.
        '404':
          $ref: '#/components/responses/NotFound'
  /external/{source}/claims/{externalId}:
    parameters:
    - $ref: '#/components/parameters/ExternalSource'
    - $ref: '#/components/parameters/ExternalId'
    put:
      tags:
      - Claims
      operationId: upsertClaimByExternalId
      summary: Create or update a claim by your ID
      security:
      - ApiKey: []
      - OAuth2:
        - claims:write
      requestBody:
        required: true
        content:
          application/json:
            schema:
              allOf:
              - type: object
                required:
                - type
                - dateOfLoss
                properties:
                  contractId:
                    $ref: '#/components/schemas/Uuid'
                  contractExternalReference:
                    $ref: '#/components/schemas/ExternalReference'
              - $ref: '#/components/schemas/ClaimInput'
      responses:
        '200':
          description: Updated.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Claim'
        '201':
          description: Created.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Claim'
        '422':
          $ref: '#/components/responses/ValidationFailed'
  /claims/{claimId}/status:
    parameters:
    - $ref: '#/components/parameters/ClaimId'
    post:
      tags:
      - Claims
      operationId: changeClaimStatus
      summary: Move a claim to another status
      security:
      - ApiKey: []
      - OAuth2:
        - claims:write
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - status
              properties:
                status:
                  $ref: '#/components/schemas/ClaimStatus'
                note:
                  type: string
                  maxLength: 2000
                settledAmount:
                  $ref: '#/components/schemas/Decimal'
      responses:
        '200':
          description: Status changed.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Claim'
        '409':
          $ref: '#/components/responses/Conflict'
  /claims/{claimId}/report:
    parameters:
    - $ref: '#/components/parameters/ClaimId'
    post:
      tags:
      - Claims
      operationId: reportClaimToInsurer
      summary: Report the claim to the insurer
      description: |
        Creates an insurer correspondence case of type `claim-report` for the claim's contract, prefilled
        with the claim data, and sends it from the given mailbox. The claim moves to `reported`.
      security:
      - ApiKey: []
      - OAuth2:
        - claims:write
        - correspondence:write
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - mailboxId
              properties:
                mailboxId:
                  $ref: '#/components/schemas/Uuid'
                attachmentDocumentIds:
                  type: array
                  maxItems: 5
                  items:
                    $ref: '#/components/schemas/Uuid'
                message:
                  type: string
                  description: Additional text for the insurer.
      responses:
        '201':
          description: Reported.
          content:
            application/json:
              schema:
                type: object
                required:
                - claim
                - correspondenceCase
                properties:
                  claim:
                    $ref: '#/components/schemas/Claim'
                  correspondenceCase:
                    $ref: '#/components/schemas/CorrespondenceCase'
        '409':
          $ref: '#/components/responses/Conflict'
  /claims/{claimId}/history:
    parameters:
    - $ref: '#/components/parameters/ClaimId'
    get:
      tags:
      - Claims
      operationId: getClaimHistory
      summary: Status history
      security:
      - ApiKey: []
      - OAuth2:
        - claims:read
      responses:
        '200':
          description: Status changes, oldest first.
          content:
            application/json:
              schema:
                type: object
                required:
                - data
                properties:
                  data:
                    type: array
                    items:
                      type: object
                      required:
                      - status
                      - changedAt
                      properties:
                        status:
                          $ref: '#/components/schemas/ClaimStatus'
                        previousStatus:
                          oneOf:
                          - $ref: '#/components/schemas/ClaimStatus'
                          - type: 'null'
                        note:
                          type:
                          - string
                          - 'null'
                        changedBy:
                          oneOf:
                          - $ref: '#/components/schemas/UserRef'
                          - type: 'null'
                        changedAt:
                          type: string
                          format: date-time
        '401':
          $ref: '#/components/responses/Unauthorized'
  /commission-statements:
    get:
      tags:
      - Commissions
      operationId: listCommissionStatements
      summary: Commission statements
      description: Courtage statements of insurers, received via BiPRO 430.5, GDV record type 0400 or uploaded manually.
      security:
      - ApiKey: []
      - OAuth2:
        - commissions:read
      parameters:
      - $ref: '#/components/parameters/Cursor'
      - $ref: '#/components/parameters/Limit'
      - name: insurerId
        in: query
        schema:
          type: string
          format: uuid
      - name: periodFrom
        in: query
        schema:
          type: string
          format: date
      - name: periodTo
        in: query
        schema:
          type: string
          format: date
      - name: status
        in: query
        schema:
          type: string
          enum:
          - received
          - reconciled
          - disputed
      responses:
        '200':
          description: A page of statements.
          content:
            application/json:
              schema:
                type: object
                required:
                - data
                - pagination
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/CommissionStatement'
                  pagination:
                    $ref: '#/components/schemas/Pagination'
        '401':
          $ref: '#/components/responses/Unauthorized'
    post:
      tags:
      - Commissions
      operationId: importCommissionStatement
      summary: Import a commission statement
      description: Upload a statement as CSV, GDV (record type 0400) or BiPRO 430.5 XML. Entries are matched to contracts
        by policy number and insurer.
      security:
      - ApiKey: []
      - OAuth2:
        - commissions:write
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              required:
              - file
              - format
              properties:
                file:
                  type: string
                  format: binary
                format:
                  type: string
                  enum:
                  - csv
                  - gdv_0400
                  - bipro_430_5
                insurerId:
                  type: string
                  format: uuid
      responses:
        '202':
          description: Import started.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CommissionStatement'
        '422':
          $ref: '#/components/responses/ValidationFailed'
  /commission-statements/{statementId}:
    parameters:
    - name: statementId
      in: path
      required: true
      schema:
        type: string
        format: uuid
    get:
      tags:
      - Commissions
      operationId: getCommissionStatement
      summary: Get a statement
      security:
      - ApiKey: []
      - OAuth2:
        - commissions:read
      responses:
        '200':
          description: The statement.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CommissionStatement'
        '404':
          $ref: '#/components/responses/NotFound'
    patch:
      tags:
      - Commissions
      operationId: updateCommissionStatement
      summary: Reconcile or dispute a statement
      security:
      - ApiKey: []
      - OAuth2:
        - commissions:write
      requestBody:
        required: true
        content:
          application/merge-patch+json:
            schema:
              type: object
              properties:
                status:
                  type: string
                  enum:
                  - received
                  - reconciled
                  - disputed
                note:
                  type:
                  - string
                  - 'null'
      responses:
        '200':
          description: Updated.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CommissionStatement'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /commission-entries:
    get:
      tags:
      - Commissions
      operationId: listCommissionEntries
      summary: Commission entries
      security:
      - ApiKey: []
      - OAuth2:
        - commissions:read
      parameters:
      - $ref: '#/components/parameters/Cursor'
      - $ref: '#/components/parameters/Limit'
      - $ref: '#/components/parameters/ContactIdFilter'
      - name: statementId
        in: query
        schema:
          type: string
          format: uuid
      - name: contractId
        in: query
        schema:
          type: string
          format: uuid
      - name: type
        in: query
        schema:
          $ref: '#/components/schemas/CommissionType'
      - name: matched
        in: query
        schema:
          type: boolean
      - name: bookedFrom
        in: query
        schema:
          type: string
          format: date
      - name: bookedTo
        in: query
        schema:
          type: string
          format: date
      responses:
        '200':
          description: A page of entries.
          content:
            application/json:
              schema:
                type: object
                required:
                - data
                - pagination
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/CommissionEntry'
                  pagination:
                    $ref: '#/components/schemas/Pagination'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /commission-entries/{entryId}:
    parameters:
    - name: entryId
      in: path
      required: true
      schema:
        type: string
        format: uuid
    patch:
      tags:
      - Commissions
      operationId: updateCommissionEntry
      summary: Match an entry to a contract
      security:
      - ApiKey: []
      - OAuth2:
        - commissions:write
      requestBody:
        required: true
        content:
          application/merge-patch+json:
            schema:
              type: object
              properties:
                contractId:
                  type:
                  - string
                  - 'null'
                  format: uuid
                note:
                  type:
                  - string
                  - 'null'
      responses:
        '200':
          description: Updated.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CommissionEntry'
        '404':
          $ref: '#/components/responses/NotFound'
  /reports/commissions:
    get:
      tags:
      - Commissions
      operationId: getCommissionReport
      summary: Commission totals
      security:
      - ApiKey: []
      - OAuth2:
        - commissions:read
      parameters:
      - name: from
        in: query
        required: true
        schema:
          type: string
          format: date
      - name: to
        in: query
        required: true
        schema:
          type: string
          format: date
      - name: groupBy
        in: query
        schema:
          type: string
          enum:
          - month
          - insurer
          - type
          - contract_type
          - owner
          default: month
      responses:
        '200':
          description: Totals per group.
          content:
            application/json:
              schema:
                type: object
                required:
                - data
                - total
                properties:
                  data:
                    type: array
                    items:
                      type: object
                      required:
                      - key
                      - label
                      - amount
                      properties:
                        key:
                          type: string
                          examples:
                          - '2026-09'
                        label:
                          type: string
                          examples:
                          - September 2026
                        amount:
                          $ref: '#/components/schemas/Decimal'
                        entries:
                          type: integer
                  total:
                    $ref: '#/components/schemas/Decimal'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /reports/cancellation-liability:
    get:
      tags:
      - Commissions
      operationId: getCancellationLiabilityReport
      summary: Open cancellation liability
      description: Acquisition commission that can still be charged back, per contract, until the liability period ends.
      security:
      - ApiKey: []
      - OAuth2:
        - commissions:read
      parameters:
      - name: asOf
        in: query
        schema:
          type: string
          format: date
      responses:
        '200':
          description: Contracts with open liability.
          content:
            application/json:
              schema:
                type: object
                required:
                - data
                - total
                properties:
                  data:
                    type: array
                    items:
                      type: object
                      required:
                      - contractId
                      - insurerName
                      - openLiability
                      - liabilityEndsOn
                      properties:
                        contractId:
                          $ref: '#/components/schemas/Uuid'
                        contactId:
                          $ref: '#/components/schemas/Uuid'
                        insurerName:
                          type: string
                        policyNumber:
                          type:
                          - string
                          - 'null'
                        openLiability:
                          $ref: '#/components/schemas/Decimal'
                        liabilityEndsOn:
                          type: string
                          format: date
                  total:
                    $ref: '#/components/schemas/Decimal'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /email-threads:
    get:
      tags:
      - Emails
      operationId: listEmailThreads
      summary: Email conversations
      description: Threads of the company's mailboxes, linked to contacts and leads.
      security:
      - ApiKey: []
      - OAuth2:
        - emails:read
      parameters:
      - $ref: '#/components/parameters/Cursor'
      - $ref: '#/components/parameters/Limit'
      - $ref: '#/components/parameters/UpdatedSince'
      - $ref: '#/components/parameters/ContactIdFilter'
      - name: leadId
        in: query
        schema:
          type: string
          format: uuid
      - name: mailboxId
        in: query
        schema:
          type: string
          format: uuid
      - name: q
        in: query
        description: Search in subject, sender and body.
        schema:
          type: string
          minLength: 2
      responses:
        '200':
          description: A page of threads, latest message first.
          content:
            application/json:
              schema:
                type: object
                required:
                - data
                - pagination
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/EmailThread'
                  pagination:
                    $ref: '#/components/schemas/Pagination'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /email-threads/{threadId}:
    parameters:
    - name: threadId
      in: path
      required: true
      schema:
        type: string
        format: uuid
    get:
      tags:
      - Emails
      operationId: getEmailThread
      summary: Get a thread with its messages
      security:
      - ApiKey: []
      - OAuth2:
        - emails:read
      responses:
        '200':
          description: The thread.
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/EmailThread'
                - type: object
                  required:
                  - messages
                  properties:
                    messages:
                      type: array
                      items:
                        $ref: '#/components/schemas/Email'
        '404':
          $ref: '#/components/responses/NotFound'
  /emails:
    post:
      tags:
      - Emails
      operationId: sendEmail
      summary: Send an email
      description: Sends from a mailbox of the company. The email is linked to the contact or lead, appears in the timeline
        and emits `email.sent`. Tracking events (delivered, opened, clicked) update the email later.
      security:
      - ApiKey: []
      - OAuth2:
        - emails:write
      parameters:
      - $ref: '#/components/parameters/IdempotencyKey'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/EmailSend'
      responses:
        '201':
          description: Sent or queued.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Email'
        '402':
          description: Not enough points for sending.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
        '422':
          $ref: '#/components/responses/ValidationFailed'
  /emails/{emailId}:
    parameters:
    - $ref: '#/components/parameters/EmailId'
    get:
      tags:
      - Emails
      operationId: getEmail
      summary: Get an email
      security:
      - ApiKey: []
      - OAuth2:
        - emails:read
      parameters:
      - name: body
        in: query
        description: Body variant to include.
        schema:
          type: string
          enum:
          - none
          - text
          - html
          default: text
      responses:
        '200':
          description: The email.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Email'
        '404':
          $ref: '#/components/responses/NotFound'
  /emails/{emailId}/attachments/{attachmentId}/content:
    parameters:
    - $ref: '#/components/parameters/EmailId'
    - name: attachmentId
      in: path
      required: true
      schema:
        type: string
        format: uuid
    get:
      tags:
      - Emails
      operationId: downloadEmailAttachment
      summary: Download an attachment
      security:
      - ApiKey: []
      - OAuth2:
        - emails:read
      responses:
        '200':
          description: The file.
          content:
            application/octet-stream:
              schema:
                type: string
                format: binary
        '404':
          $ref: '#/components/responses/NotFound'
  /email-templates:
    get:
      tags:
      - Emails
      operationId: listEmailTemplates
      summary: Email templates
      description: Templates of the company with their placeholders, e.g. `{{contact.firstName}}`.
      security:
      - ApiKey: []
      - OAuth2:
        - emails:read
      responses:
        '200':
          description: Templates.
          content:
            application/json:
              schema:
                type: object
                required:
                - data
                properties:
                  data:
                    type: array
                    items:
                      type: object
                      required:
                      - id
                      - name
                      - subject
                      properties:
                        id:
                          $ref: '#/components/schemas/Uuid'
                        name:
                          type: string
                          examples:
                          - Geburtstagsgruß
                        subject:
                          type: string
                        category:
                          type:
                          - string
                          - 'null'
                        placeholders:
                          type: array
                          items:
                            type: string
                          examples:
                          - - contact.firstName
                            - contact.lastName
                            - user.signature
                        updatedAt:
                          type: string
                          format: date-time
        '401':
          $ref: '#/components/responses/Unauthorized'
  /segments:
    get:
      tags:
      - Marketing
      operationId: listSegments
      summary: Contact segments
      description: Saved contact filters, used as audiences for funnels and automations.
      security:
      - ApiKey: []
      - OAuth2:
        - marketing:read
      responses:
        '200':
          description: Segments.
          content:
            application/json:
              schema:
                type: object
                required:
                - data
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Segment'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /segments/{segmentId}/contacts:
    parameters:
    - name: segmentId
      in: path
      required: true
      schema:
        type: string
        format: uuid
    get:
      tags:
      - Marketing
      operationId: listSegmentContacts
      summary: Contacts in a segment
      security:
      - ApiKey: []
      - OAuth2:
        - marketing:read
        - contacts:read
      parameters:
      - $ref: '#/components/parameters/Cursor'
      - $ref: '#/components/parameters/Limit'
      responses:
        '200':
          description: A page of contacts that currently match.
          content:
            application/json:
              schema:
                type: object
                required:
                - data
                - pagination
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/ContactSummary'
                  pagination:
                    $ref: '#/components/schemas/Pagination'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /funnels:
    get:
      tags:
      - Marketing
      operationId: listFunnels
      summary: Email funnels
      security:
      - ApiKey: []
      - OAuth2:
        - marketing:read
      parameters:
      - name: status
        in: query
        schema:
          $ref: '#/components/schemas/FunnelStatus'
      responses:
        '200':
          description: Funnels with their key figures.
          content:
            application/json:
              schema:
                type: object
                required:
                - data
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Funnel'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /funnels/{funnelId}:
    parameters:
    - $ref: '#/components/parameters/FunnelId'
    get:
      tags:
      - Marketing
      operationId: getFunnel
      summary: Get a funnel
      security:
      - ApiKey: []
      - OAuth2:
        - marketing:read
      responses:
        '200':
          description: The funnel with its steps.
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/Funnel'
                - type: object
                  properties:
                    steps:
                      type: array
                      items:
                        type: object
                        required:
                        - id
                        - type
                        properties:
                          id:
                            $ref: '#/components/schemas/Uuid'
                          type:
                            type: string
                            enum:
                            - trigger
                            - send_email
                            - delay
                            - condition
                            - end
                          label:
                            type: string
                          sent:
                            type: integer
                          opened:
                            type: integer
                          clicked:
                            type: integer
        '404':
          $ref: '#/components/responses/NotFound'
  /funnels/{funnelId}/enrollments:
    parameters:
    - $ref: '#/components/parameters/FunnelId'
    get:
      tags:
      - Marketing
      operationId: listFunnelEnrollments
      summary: Contacts in a funnel
      security:
      - ApiKey: []
      - OAuth2:
        - marketing:read
      parameters:
      - $ref: '#/components/parameters/Cursor'
      - $ref: '#/components/parameters/Limit'
      - name: status
        in: query
        schema:
          type: string
          enum:
          - pending
          - in_progress
          - completed
          - failed
          - unsubscribed
      responses:
        '200':
          description: A page of enrollments.
          content:
            application/json:
              schema:
                type: object
                required:
                - data
                - pagination
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Enrollment'
                  pagination:
                    $ref: '#/components/schemas/Pagination'
        '401':
          $ref: '#/components/responses/Unauthorized'
    post:
      tags:
      - Marketing
      operationId: enrollInFunnel
      summary: Add contacts to a funnel
      security:
      - ApiKey: []
      - OAuth2:
        - marketing:write
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - contactIds
              properties:
                contactIds:
                  type: array
                  minItems: 1
                  maxItems: 500
                  items:
                    $ref: '#/components/schemas/Uuid'
      responses:
        '202':
          description: Enrollment queued; contacts that opted out are skipped.
          content:
            application/json:
              schema:
                type: object
                required:
                - enrolled
                - skipped
                properties:
                  enrolled:
                    type: integer
                  skipped:
                    type: array
                    items:
                      type: object
                      properties:
                        contactId:
                          $ref: '#/components/schemas/Uuid'
                        reason:
                          type: string
                          enum:
                          - opted_out
                          - no_email
                          - already_enrolled
                          - not_found
        '401':
          $ref: '#/components/responses/Unauthorized'
  /funnels/{funnelId}/enrollments/{contactId}:
    parameters:
    - $ref: '#/components/parameters/FunnelId'
    - $ref: '#/components/parameters/ContactId'
    delete:
      tags:
      - Marketing
      operationId: removeFromFunnel
      summary: Remove a contact from a funnel
      security:
      - ApiKey: []
      - OAuth2:
        - marketing:write
      responses:
        '204':
          description: Removed.
        '404':
          $ref: '#/components/responses/NotFound'
  /email-opt-outs:
    get:
      tags:
      - Marketing
      operationId: listEmailOptOuts
      summary: Unsubscribed addresses
      security:
      - ApiKey: []
      - OAuth2:
        - marketing:read
      parameters:
      - $ref: '#/components/parameters/Cursor'
      - $ref: '#/components/parameters/Limit'
      - name: email
        in: query
        schema:
          type: string
          format: email
      responses:
        '200':
          description: A page of opt-outs.
          content:
            application/json:
              schema:
                type: object
                required:
                - data
                - pagination
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/EmailOptOut'
                  pagination:
                    $ref: '#/components/schemas/Pagination'
        '401':
          $ref: '#/components/responses/Unauthorized'
    post:
      tags:
      - Marketing
      operationId: createEmailOptOut
      summary: Record an opt-out
      description: E.g. when the customer unsubscribed in your system. Opted-out addresses never receive marketing emails.
      security:
      - ApiKey: []
      - OAuth2:
        - marketing:write
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - email
              properties:
                email:
                  type: string
                  format: email
                reason:
                  type: string
                  maxLength: 500
      responses:
        '201':
          description: Recorded.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EmailOptOut'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /email-opt-outs/{email}:
    parameters:
    - name: email
      in: path
      required: true
      schema:
        type: string
        format: email
    delete:
      tags:
      - Marketing
      operationId: deleteEmailOptOut
      summary: Remove an opt-out
      description: Only allowed with documented renewed consent of the customer.
      security:
      - ApiKey: []
      - OAuth2:
        - marketing:write
      responses:
        '204':
          description: Removed.
        '404':
          $ref: '#/components/responses/NotFound'
  /automations:
    get:
      tags:
      - Automations
      operationId: listAutomations
      summary: List automations
      security:
      - ApiKey: []
      - OAuth2:
        - automations:read
      parameters:
      - name: status
        in: query
        schema:
          type: string
          enum:
          - draft
          - active
          - paused
          - completed
      - name: trigger
        in: query
        schema:
          $ref: '#/components/schemas/AutomationTrigger'
      responses:
        '200':
          description: Automations.
          content:
            application/json:
              schema:
                type: object
                required:
                - data
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Automation'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /automations/{automationId}:
    parameters:
    - $ref: '#/components/parameters/AutomationId'
    get:
      tags:
      - Automations
      operationId: getAutomation
      summary: Get an automation
      security:
      - ApiKey: []
      - OAuth2:
        - automations:read
      responses:
        '200':
          description: The automation with its steps.
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/Automation'
                - type: object
                  properties:
                    steps:
                      type: array
                      items:
                        type: object
                        required:
                        - id
                        - type
                        properties:
                          id:
                            $ref: '#/components/schemas/Uuid'
                          type:
                            type: string
                            enum:
                            - trigger
                            - delay
                            - condition
                            - wait_for_reply
                            - change_status
                            - add_tag
                            - remove_tag
                            - add_label
                            - create_note
                            - set_custom_field
                            - create_task
                            - send_email
                            - webhook
                            - end
                          label:
                            type: string
        '404':
          $ref: '#/components/responses/NotFound'
  /automations/{automationId}/enrollments:
    parameters:
    - $ref: '#/components/parameters/AutomationId'
    get:
      tags:
      - Automations
      operationId: listAutomationEnrollments
      summary: Runs of an automation
      security:
      - ApiKey: []
      - OAuth2:
        - automations:read
      parameters:
      - $ref: '#/components/parameters/Cursor'
      - $ref: '#/components/parameters/Limit'
      - name: status
        in: query
        schema:
          type: string
          enum:
          - active
          - completed
          - failed
          - cancelled
      responses:
        '200':
          description: A page of enrollments.
          content:
            application/json:
              schema:
                type: object
                required:
                - data
                - pagination
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Enrollment'
                  pagination:
                    $ref: '#/components/schemas/Pagination'
        '401':
          $ref: '#/components/responses/Unauthorized'
    post:
      tags:
      - Automations
      operationId: triggerAutomation
      summary: Start an automation for a contact or lead
      description: Only for automations with the trigger `manual` or `api`.
      security:
      - ApiKey: []
      - OAuth2:
        - automations:write
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - subjectType
              - subjectId
              properties:
                subjectType:
                  type: string
                  enum:
                  - contact
                  - lead
                subjectId:
                  $ref: '#/components/schemas/Uuid'
                variables:
                  type: object
                  description: Values available to the automation steps.
                  additionalProperties:
                    type:
                    - string
                    - number
                    - boolean
      responses:
        '202':
          description: Started.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Enrollment'
        '409':
          $ref: '#/components/responses/Conflict'
  /calculators:
    get:
      tags:
      - Calculators
      operationId: listCalculators
      summary: Calculators and needs analyses
      description: Calculators the company has licensed (e.g. pension gap, disability need, household finances check).
      security:
      - ApiKey: []
      - OAuth2:
        - calculators:read
      responses:
        '200':
          description: Calculators.
          content:
            application/json:
              schema:
                type: object
                required:
                - data
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Calculator'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /calculators/{slug}:
    parameters:
    - $ref: '#/components/parameters/CalculatorSlug'
    get:
      tags:
      - Calculators
      operationId: getCalculator
      summary: Get a calculator
      description: Includes the JSON schema of the result data, so you can read saved calculations field by field.
      security:
      - ApiKey: []
      - OAuth2:
        - calculators:read
      responses:
        '200':
          description: The calculator.
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/Calculator'
                - type: object
                  properties:
                    resultSchema:
                      type: object
                      description: JSON Schema of `Calculation.data`.
                      additionalProperties: true
        '404':
          $ref: '#/components/responses/NotFound'
  /calculators/{slug}/launch-links:
    parameters:
    - $ref: '#/components/parameters/CalculatorSlug'
    post:
      tags:
      - Calculators
      operationId: createCalculatorLaunchLink
      summary: Open a calculator for a contact
      description: Returns a short-lived signed URL that opens the calculator with the contact's data prefilled, e.g. from
        a button in your AMS.
      security:
      - ApiKey: []
      - OAuth2:
        - calculators:write
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - contactId
              properties:
                contactId:
                  $ref: '#/components/schemas/Uuid'
                partnerContactId:
                  $ref: '#/components/schemas/Uuid'
                returnUrl:
                  type: string
                  format: uri
                expiresInSeconds:
                  type: integer
                  minimum: 60
                  maximum: 3600
                  default: 900
      responses:
        '201':
          description: Launch link.
          content:
            application/json:
              schema:
                type: object
                required:
                - url
                - expiresAt
                properties:
                  url:
                    type: string
                    format: uri
                  expiresAt:
                    type: string
                    format: date-time
        '404':
          $ref: '#/components/responses/NotFound'
  /contacts/{contactId}/calculations:
    parameters:
    - $ref: '#/components/parameters/ContactId'
    get:
      tags:
      - Calculators
      operationId: listContactCalculations
      summary: Saved calculations of a contact
      security:
      - ApiKey: []
      - OAuth2:
        - calculators:read
      responses:
        '200':
          description: Calculations, newest first.
          content:
            application/json:
              schema:
                type: object
                required:
                - data
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Calculation'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /calculations/{calculationId}:
    parameters:
    - name: calculationId
      in: path
      required: true
      schema:
        type: string
        format: uuid
    get:
      tags:
      - Calculators
      operationId: getCalculation
      summary: Get a calculation
      security:
      - ApiKey: []
      - OAuth2:
        - calculators:read
      responses:
        '200':
          description: The calculation.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Calculation'
        '404':
          $ref: '#/components/responses/NotFound'
  /offer-processes/{offerProcessId}:
    parameters:
    - name: offerProcessId
      in: path
      required: true
      schema:
        type: string
        format: uuid
    get:
      tags:
      - Offers
      operationId: getOfferProcess
      summary: Get an offer process
      security:
      - ApiKey: []
      - OAuth2:
        - contracts:read
      responses:
        '200':
          description: The process with tariffs and documents.
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/OfferProcess'
                - type: object
                  properties:
                    accessUrl:
                      type:
                      - string
                      - 'null'
                      format: uri
                      description: Continue the comparison at the platform.
                    results:
                      type: array
                      items:
                        type: object
                        properties:
                          insurerName:
                            type: string
                          tariffName:
                            type: string
                          premium:
                            $ref: '#/components/schemas/Decimal'
                          paymentFrequency:
                            $ref: '#/components/schemas/PaymentFrequency'
                          rating:
                            type:
                            - string
                            - 'null'
                            examples:
                            - FFF
        '404':
          $ref: '#/components/responses/NotFound'
  /advice-records:
    get:
      tags:
      - Advice documentation
      operationId: listAdviceRecords
      summary: Advice records
      description: Documented consultations according to IDD (§ 61 VVG), incl. needs, recommendation and customer decision.
      security:
      - ApiKey: []
      - OAuth2:
        - advice:read
      parameters:
      - $ref: '#/components/parameters/Cursor'
      - $ref: '#/components/parameters/Limit'
      - $ref: '#/components/parameters/UpdatedSince'
      - $ref: '#/components/parameters/ContactIdFilter'
      responses:
        '200':
          description: A page of advice records.
          content:
            application/json:
              schema:
                type: object
                required:
                - data
                - pagination
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/AdviceRecord'
                  pagination:
                    $ref: '#/components/schemas/Pagination'
        '401':
          $ref: '#/components/responses/Unauthorized'
    post:
      tags:
      - Advice documentation
      operationId: createAdviceRecord
      summary: Document a consultation
      security:
      - ApiKey: []
      - OAuth2:
        - advice:write
      parameters:
      - $ref: '#/components/parameters/IdempotencyKey'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AdviceRecordInput'
      responses:
        '201':
          description: Created.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AdviceRecord'
        '422':
          $ref: '#/components/responses/ValidationFailed'
  /advice-records/{adviceRecordId}:
    parameters:
    - $ref: '#/components/parameters/AdviceRecordId'
    get:
      tags:
      - Advice documentation
      operationId: getAdviceRecord
      summary: Get an advice record
      security:
      - ApiKey: []
      - OAuth2:
        - advice:read
      responses:
        '200':
          description: The advice record.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AdviceRecord'
        '404':
          $ref: '#/components/responses/NotFound'
    patch:
      tags:
      - Advice documentation
      operationId: updateAdviceRecord
      summary: Update an advice record
      description: Records are locked once the document has been signed.
      security:
      - ApiKey: []
      - OAuth2:
        - advice:write
      requestBody:
        required: true
        content:
          application/merge-patch+json:
            schema:
              $ref: '#/components/schemas/AdviceRecordInput'
      responses:
        '200':
          description: Updated.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AdviceRecord'
        '409':
          $ref: '#/components/responses/Conflict'
  /advice-records/{adviceRecordId}/document:
    parameters:
    - $ref: '#/components/parameters/AdviceRecordId'
    post:
      tags:
      - Advice documentation
      operationId: generateAdviceDocument
      summary: Create the advice protocol PDF
      description: Renders the protocol with the company's template and files it with the contact (type `advice_documentation`).
        Send it for signature via `POST /signature-requests`.
      security:
      - ApiKey: []
      - OAuth2:
        - advice:write
        - documents:write
      responses:
        '201':
          description: Document created.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Document'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /landing-pages:
    get:
      tags:
      - Landing pages
      operationId: listLandingPages
      summary: Landing pages
      security:
      - ApiKey: []
      - OAuth2:
        - marketing:read
      responses:
        '200':
          description: Landing pages with their lead figures.
          content:
            application/json:
              schema:
                type: object
                required:
                - data
                properties:
                  data:
                    type: array
                    items:
                      type: object
                      required:
                      - id
                      - slug
                      - title
                      - status
                      - url
                      properties:
                        id:
                          $ref: '#/components/schemas/Uuid'
                        slug:
                          type: string
                          examples:
                          - bu-check
                        title:
                          type: string
                          examples:
                          - BU-Check für Selbstständige
                        status:
                          type: string
                          enum:
                          - draft
                          - published
                          - archived
                        url:
                          type: string
                          format: uri
                        calculatorSlug:
                          type:
                          - string
                          - 'null'
                        views:
                          type: integer
                        submissions:
                          type: integer
                        conversionRate:
                          type: number
                          description: Submissions per view.
        '401':
          $ref: '#/components/responses/Unauthorized'
  /landing-pages/{landingPageId}/submissions:
    parameters:
    - name: landingPageId
      in: path
      required: true
      schema:
        type: string
        format: uuid
    get:
      tags:
      - Landing pages
      operationId: listLandingPageSubmissions
      summary: Submissions of a landing page
      security:
      - ApiKey: []
      - OAuth2:
        - marketing:read
        - leads:read
      parameters:
      - $ref: '#/components/parameters/Cursor'
      - $ref: '#/components/parameters/Limit'
      responses:
        '200':
          description: A page of submissions.
          content:
            application/json:
              schema:
                type: object
                required:
                - data
                - pagination
                properties:
                  data:
                    type: array
                    items:
                      type: object
                      required:
                      - id
                      - leadId
                      - submittedAt
                      properties:
                        id:
                          $ref: '#/components/schemas/Uuid'
                        leadId:
                          $ref: '#/components/schemas/Uuid'
                        calculationData:
                          type:
                          - object
                          - 'null'
                          additionalProperties: true
                        sourceUrl:
                          type:
                          - string
                          - 'null'
                          format: uri
                        submittedAt:
                          type: string
                          format: date-time
                  pagination:
                    $ref: '#/components/schemas/Pagination'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /search:
    get:
      tags:
      - Search
      operationId: search
      summary: Search across the company
      description: One query over contacts, leads, contracts and documents, ranked by relevance.
      security:
      - ApiKey: []
      - OAuth2:
        - contacts:read
      parameters:
      - name: q
        in: query
        required: true
        schema:
          type: string
          minLength: 2
      - name: types
        in: query
        description: Comma-separated object types.
        schema:
          type: string
          default: contact,lead,contract,document
      - name: limit
        in: query
        schema:
          type: integer
          minimum: 1
          maximum: 50
          default: 10
      responses:
        '200':
          description: Hits grouped by type.
          content:
            application/json:
              schema:
                type: object
                required:
                - data
                properties:
                  data:
                    type: array
                    items:
                      type: object
                      required:
                      - type
                      - id
                      - title
                      properties:
                        type:
                          type: string
                          enum:
                          - contact
                          - lead
                          - contract
                          - document
                        id:
                          $ref: '#/components/schemas/Uuid'
                        title:
                          type: string
                          examples:
                          - Manni Mustermann
                        subtitle:
                          type:
                          - string
                          - 'null'
                          examples:
                          - 01069 Dresden
                        contactId:
                          type:
                          - string
                          - 'null'
                          format: uuid
                        highlight:
                          type:
                          - string
                          - 'null'
                        score:
                          type: number
        '401':
          $ref: '#/components/responses/Unauthorized'
  /reports/portfolio:
    get:
      tags:
      - Reports
      operationId: getPortfolioReport
      summary: Portfolio overview
      description: Contracts and annual premium of the portfolio, grouped by contract type, insurer or owner.
      security:
      - ApiKey: []
      - OAuth2:
        - reports:read
      parameters:
      - name: groupBy
        in: query
        schema:
          type: string
          enum:
          - type_group
          - type
          - insurer
          - owner
          - status
          default: type_group
      - name: asOf
        in: query
        schema:
          type: string
          format: date
      - name: ownerId
        in: query
        schema:
          type: string
          format: uuid
      responses:
        '200':
          description: Portfolio figures.
          content:
            application/json:
              schema:
                type: object
                required:
                - data
                - totals
                properties:
                  data:
                    type: array
                    items:
                      type: object
                      required:
                      - key
                      - label
                      - contracts
                      - annualPremium
                      properties:
                        key:
                          type: string
                          examples:
                          - liability_legal
                        label:
                          type: string
                          examples:
                          - Haftpflicht & Recht
                        contracts:
                          type: integer
                        contacts:
                          type: integer
                        annualPremium:
                          $ref: '#/components/schemas/Decimal'
                        share:
                          type: number
                          description: Share of the total annual premium.
                  totals:
                    type: object
                    properties:
                      contracts:
                        type: integer
                      contacts:
                        type: integer
                      annualPremium:
                        $ref: '#/components/schemas/Decimal'
                      averageContractsPerContact:
                        type: number
        '401':
          $ref: '#/components/responses/Unauthorized'
  /reports/renewals:
    get:
      tags:
      - Reports
      operationId: getRenewalsReport
      summary: Expiring contracts
      description: Contracts whose end date or main renewal date falls into the window, e.g. for the annual review (Hauptfälligkeit).
      security:
      - ApiKey: []
      - OAuth2:
        - reports:read
      parameters:
      - name: from
        in: query
        required: true
        schema:
          type: string
          format: date
      - name: to
        in: query
        required: true
        schema:
          type: string
          format: date
      - $ref: '#/components/parameters/Cursor'
      - $ref: '#/components/parameters/Limit'
      responses:
        '200':
          description: A page of contracts.
          content:
            application/json:
              schema:
                type: object
                required:
                - data
                - pagination
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Contract'
                  pagination:
                    $ref: '#/components/schemas/Pagination'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /reports/cross-selling:
    get:
      tags:
      - Reports
      operationId: getCrossSellingReport
      summary: Coverage gaps
      description: Private contacts without key covers (liability, household contents, disability, pension) and business contacts
        without business liability, with a priority score.
      security:
      - ApiKey: []
      - OAuth2:
        - reports:read
      parameters:
      - name: gap
        in: query
        schema:
          $ref: '#/components/schemas/ContractType'
      - $ref: '#/components/parameters/Cursor'
      - $ref: '#/components/parameters/Limit'
      responses:
        '200':
          description: A page of contacts with their gaps.
          content:
            application/json:
              schema:
                type: object
                required:
                - data
                - pagination
                properties:
                  data:
                    type: array
                    items:
                      type: object
                      required:
                      - contact
                      - gaps
                      - score
                      properties:
                        contact:
                          $ref: '#/components/schemas/ContactSummary'
                        gaps:
                          type: array
                          items:
                            $ref: '#/components/schemas/ContractType'
                        score:
                          type: number
                          minimum: 0
                          maximum: 100
                  pagination:
                    $ref: '#/components/schemas/Pagination'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /reports/pipeline:
    get:
      tags:
      - Reports
      operationId: getPipelineReport
      summary: Lead pipeline
      security:
      - ApiKey: []
      - OAuth2:
        - reports:read
      parameters:
      - name: from
        in: query
        schema:
          type: string
          format: date
      - name: to
        in: query
        schema:
          type: string
          format: date
      responses:
        '200':
          description: Leads per stage and source with conversion rate.
          content:
            application/json:
              schema:
                type: object
                required:
                - stages
                - sources
                - conversionRate
                properties:
                  stages:
                    type: array
                    items:
                      type: object
                      properties:
                        stage:
                          $ref: '#/components/schemas/LeadStage'
                        count:
                          type: integer
                  sources:
                    type: array
                    items:
                      type: object
                      properties:
                        source:
                          $ref: '#/components/schemas/LeadSource'
                        count:
                          type: integer
                        converted:
                          type: integer
                  conversionRate:
                    type: number
                  averageDaysToConversion:
                    type:
                    - number
                    - 'null'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /reports/activity:
    get:
      tags:
      - Reports
      operationId: getActivityReport
      summary: Team activity
      security:
      - ApiKey: []
      - OAuth2:
        - reports:read
      parameters:
      - name: from
        in: query
        required: true
        schema:
          type: string
          format: date
      - name: to
        in: query
        required: true
        schema:
          type: string
          format: date
      responses:
        '200':
          description: Activity per user.
          content:
            application/json:
              schema:
                type: object
                required:
                - data
                properties:
                  data:
                    type: array
                    items:
                      type: object
                      required:
                      - user
                      properties:
                        user:
                          $ref: '#/components/schemas/UserRef'
                        contactsCreated:
                          type: integer
                        contractsCreated:
                          type: integer
                        newAnnualPremium:
                          $ref: '#/components/schemas/Decimal'
                        tasksCompleted:
                          type: integer
                        appointments:
                          type: integer
                        emailsSent:
                          type: integer
                        leadsConverted:
                          type: integer
        '401':
          $ref: '#/components/responses/Unauthorized'
  /imports:
    get:
      tags:
      - Imports
      operationId: listImports
      summary: Contact imports
      security:
      - ApiKey: []
      - OAuth2:
        - imports:write
      parameters:
      - $ref: '#/components/parameters/Cursor'
      - $ref: '#/components/parameters/Limit'
      responses:
        '200':
          description: A page of imports.
          content:
            application/json:
              schema:
                type: object
                required:
                - data
                - pagination
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/ImportJob'
                  pagination:
                    $ref: '#/components/schemas/Pagination'
        '401':
          $ref: '#/components/responses/Unauthorized'
    post:
      tags:
      - Imports
      operationId: createImport
      summary: Import contacts from CSV or Excel
      description: Upload a file and a column mapping. The file is analyzed first; rows are written after `commit`. Duplicates
        are detected by email (private) and company name (business).
      security:
      - ApiKey: []
      - OAuth2:
        - imports:write
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              required:
              - file
              properties:
                file:
                  type: string
                  format: binary
                contactType:
                  $ref: '#/components/schemas/ContactType'
                mapping:
                  type: string
                  description: 'JSON object column name → contact field key, e.g. `{"Vorname": "firstName", "PLZ": "address.zipCode"}`.
                    Omit to get a suggested mapping.'
                tags:
                  type: string
                  description: Comma-separated tags added to every imported contact.
                ownerId:
                  type: string
                  format: uuid
      responses:
        '202':
          description: Analysis started.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ImportJob'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /imports/{importId}:
    parameters:
    - $ref: '#/components/parameters/ImportId'
    get:
      tags:
      - Imports
      operationId: getImport
      summary: Get an import
      security:
      - ApiKey: []
      - OAuth2:
        - imports:write
      responses:
        '200':
          description: Status, suggested mapping and row counts.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ImportJob'
        '404':
          $ref: '#/components/responses/NotFound'
  /imports/{importId}/commit:
    parameters:
    - $ref: '#/components/parameters/ImportId'
    post:
      tags:
      - Imports
      operationId: commitImport
      summary: Write the analyzed rows
      security:
      - ApiKey: []
      - OAuth2:
        - imports:write
      requestBody:
        required: false
        content:
          application/json:
            schema:
              type: object
              properties:
                duplicates:
                  type: string
                  enum:
                  - skip
                  - update
                  - create
                  default: skip
      responses:
        '202':
          description: Import running.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ImportJob'
        '409':
          $ref: '#/components/responses/Conflict'
  /imports/{importId}/rows:
    parameters:
    - $ref: '#/components/parameters/ImportId'
    get:
      tags:
      - Imports
      operationId: listImportRows
      summary: Row results
      security:
      - ApiKey: []
      - OAuth2:
        - imports:write
      parameters:
      - $ref: '#/components/parameters/Cursor'
      - $ref: '#/components/parameters/Limit'
      - name: outcome
        in: query
        schema:
          type: string
          enum:
          - created
          - updated
          - duplicate
          - skipped
          - failed
      responses:
        '200':
          description: A page of rows.
          content:
            application/json:
              schema:
                type: object
                required:
                - data
                - pagination
                properties:
                  data:
                    type: array
                    items:
                      type: object
                      required:
                      - row
                      - outcome
                      properties:
                        row:
                          type: integer
                        outcome:
                          type: string
                          enum:
                          - created
                          - updated
                          - duplicate
                          - skipped
                          - failed
                        contactId:
                          type:
                          - string
                          - 'null'
                          format: uuid
                        errors:
                          type: array
                          items:
                            type: string
                  pagination:
                    $ref: '#/components/schemas/Pagination'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /document-templates:
    get:
      tags:
      - Document generation
      operationId: listDocumentTemplates
      summary: Print templates
      description: Company templates for letters, broker agreements, cover notes and protocols.
      security:
      - ApiKey: []
      - OAuth2:
        - documents:read
      responses:
        '200':
          description: Templates.
          content:
            application/json:
              schema:
                type: object
                required:
                - data
                properties:
                  data:
                    type: array
                    items:
                      type: object
                      required:
                      - id
                      - name
                      - category
                      properties:
                        id:
                          $ref: '#/components/schemas/Uuid'
                        name:
                          type: string
                          examples:
                          - Maklervertrag
                        category:
                          type: string
                          enum:
                          - letter
                          - broker_agreement
                          - power_of_attorney
                          - privacy
                          - advice_protocol
                          - cover_note
                          - other
                        placeholders:
                          type: array
                          items:
                            type: string
                        hasSignatureFields:
                          type: boolean
        '401':
          $ref: '#/components/responses/Unauthorized'
  /documents/generate:
    post:
      tags:
      - Document generation
      operationId: generateDocument
      summary: Generate a document from a template
      description: Renders the template with contact (and optionally contract) data as PDF and files it with the contact.
      security:
      - ApiKey: []
      - OAuth2:
        - documents:write
      parameters:
      - $ref: '#/components/parameters/IdempotencyKey'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - templateId
              - contactId
              properties:
                templateId:
                  $ref: '#/components/schemas/Uuid'
                contactId:
                  $ref: '#/components/schemas/Uuid'
                contractId:
                  $ref: '#/components/schemas/Uuid'
                variables:
                  type: object
                  description: Values for free placeholders of the template.
                  additionalProperties:
                    type: string
                filename:
                  type: string
                  maxLength: 255
      responses:
        '201':
          description: Generated document.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Document'
        '422':
          $ref: '#/components/responses/ValidationFailed'
  /contacts/{contactId}/privacy/data-export:
    parameters:
    - $ref: '#/components/parameters/ContactId'
    post:
      tags:
      - Privacy
      operationId: requestContactDataExport
      summary: Data subject access request (Art. 15 GDPR)
      description: Compiles all personal data of the contact (master data, contracts, documents, notes, emails, consents)
        into a ZIP.
      security:
      - ApiKey: []
      - OAuth2:
        - privacy:write
      responses:
        '202':
          description: Export queued.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PrivacyRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /contacts/{contactId}/privacy/erasure:
    parameters:
    - $ref: '#/components/parameters/ContactId'
    post:
      tags:
      - Privacy
      operationId: requestContactErasure
      summary: Erasure request (Art. 17 GDPR)
      description: |
        Schedules the deletion of the contact and all related data. Data with a statutory retention
        period (e.g. advice documentation, § 257 HGB) is blocked instead of deleted until the period ends.
      security:
      - ApiKey: []
      - OAuth2:
        - privacy:write
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - reason
              properties:
                reason:
                  type: string
                  maxLength: 1000
                requestedAt:
                  type: string
                  format: date-time
                  description: When the data subject asked.
      responses:
        '202':
          description: Erasure scheduled.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PrivacyRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /privacy-requests:
    get:
      tags:
      - Privacy
      operationId: listPrivacyRequests
      summary: Privacy requests
      security:
      - ApiKey: []
      - OAuth2:
        - privacy:write
      parameters:
      - $ref: '#/components/parameters/Cursor'
      - $ref: '#/components/parameters/Limit'
      - name: type
        in: query
        schema:
          type: string
          enum:
          - data_export
          - erasure
      responses:
        '200':
          description: A page of requests.
          content:
            application/json:
              schema:
                type: object
                required:
                - data
                - pagination
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/PrivacyRequest'
                  pagination:
                    $ref: '#/components/schemas/Pagination'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /roles:
    get:
      tags:
      - Administration
      operationId: listRoles
      summary: Roles and permissions
      security:
      - ApiKey: []
      - OAuth2:
        - users:read
      responses:
        '200':
          description: Roles of the company.
          content:
            application/json:
              schema:
                type: object
                required:
                - data
                properties:
                  data:
                    type: array
                    items:
                      type: object
                      required:
                      - id
                      - name
                      - isSystem
                      - permissions
                      properties:
                        id:
                          $ref: '#/components/schemas/Uuid'
                        name:
                          type: string
                          examples:
                          - Innendienst
                        isSystem:
                          type: boolean
                        hasAllPermissions:
                          type: boolean
                        permissions:
                          type: array
                          items:
                            type: string
                            examples:
                            - permission.contracts.edit
                        userCount:
                          type: integer
        '401':
          $ref: '#/components/responses/Unauthorized'
  /holding/companies:
    get:
      tags:
      - Administration
      operationId: listHoldingCompanies
      summary: Companies of a group
      description: 'For the leading company of a group (Holding): the member companies with key figures. Read-only.'
      security:
      - ApiKey: []
      - OAuth2:
        - company:read
      responses:
        '200':
          description: Member companies.
          content:
            application/json:
              schema:
                type: object
                required:
                - data
                properties:
                  data:
                    type: array
                    items:
                      type: object
                      required:
                      - id
                      - name
                      properties:
                        id:
                          $ref: '#/components/schemas/Uuid'
                        name:
                          type: string
                        users:
                          type: integer
                        contacts:
                          type: integer
                        contracts:
                          type: integer
                        annualPremium:
                          $ref: '#/components/schemas/Decimal'
        '403':
          $ref: '#/components/responses/Forbidden'
  /custom-fields/{customFieldId}:
    parameters:
    - name: customFieldId
      in: path
      required: true
      schema:
        type: string
        format: uuid
    patch:
      tags:
      - Administration
      operationId: updateCustomField
      summary: Change a custom field
      security:
      - ApiKey: []
      - OAuth2:
        - admin:write
      requestBody:
        required: true
        content:
          application/merge-patch+json:
            schema:
              $ref: '#/components/schemas/CustomFieldDefinitionInput'
      responses:
        '200':
          description: Updated.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CustomFieldDefinition'
        '401':
          $ref: '#/components/responses/Unauthorized'
    delete:
      tags:
      - Administration
      operationId: deleteCustomField
      summary: Remove a custom field
      description: Values are removed from all contacts in the background.
      security:
      - ApiKey: []
      - OAuth2:
        - admin:write
      responses:
        '202':
          description: Removal scheduled.
        '404':
          $ref: '#/components/responses/NotFound'
  /lead-stages/{stageId}:
    parameters:
    - name: stageId
      in: path
      required: true
      schema:
        type: string
        format: uuid
    patch:
      tags:
      - Administration
      operationId: updateLeadStage
      summary: Rename, recolor or reorder a stage
      security:
      - ApiKey: []
      - OAuth2:
        - admin:write
      requestBody:
        required: true
        content:
          application/merge-patch+json:
            schema:
              type: object
              properties:
                name:
                  type: string
                  maxLength: 100
                color:
                  $ref: '#/components/schemas/LabelColor'
                position:
                  type: integer
                  minimum: 0
      responses:
        '200':
          description: Updated.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LeadStage'
        '401':
          $ref: '#/components/responses/Unauthorized'
    delete:
      tags:
      - Administration
      operationId: deleteLeadStage
      summary: Remove a stage
      description: System stages (`new`, `converted`) cannot be removed. Leads move to `moveLeadsTo`.
      security:
      - ApiKey: []
      - OAuth2:
        - admin:write
      parameters:
      - name: moveLeadsTo
        in: query
        required: true
        schema:
          type: string
          format: uuid
      responses:
        '204':
          description: Removed.
        '409':
          $ref: '#/components/responses/Conflict'
  /tags/{tagId}:
    parameters:
    - name: tagId
      in: path
      required: true
      schema:
        type: string
        format: uuid
    patch:
      tags:
      - Administration
      operationId: renameTag
      summary: Rename a tag
      security:
      - ApiKey: []
      - OAuth2:
        - admin:write
      requestBody:
        required: true
        content:
          application/merge-patch+json:
            schema:
              type: object
              required:
              - name
              properties:
                name:
                  type: string
                  maxLength: 50
      responses:
        '200':
          description: Renamed on all contacts.
          content:
            application/json:
              schema:
                type: object
                required:
                - id
                - name
                properties:
                  id:
                    $ref: '#/components/schemas/Uuid'
                  name:
                    type: string
        '409':
          $ref: '#/components/responses/Conflict'
    delete:
      tags:
      - Administration
      operationId: deleteTag
      summary: Delete a tag
      description: Removes the tag from all contacts.
      security:
      - ApiKey: []
      - OAuth2:
        - admin:write
      responses:
        '204':
          description: Deleted.
        '401':
          $ref: '#/components/responses/Unauthorized'
  /reference/{list}:
    parameters:
    - name: list
      in: path
      required: true
      schema:
        type: string
        enum:
        - countries
        - legal-forms
        - health-insurance-funds
        - gdv-lines
        - salutations
        - marital-statuses
        - employment-statuses
        - payment-frequencies
    get:
      tags:
      - Reference data
      operationId: getReferenceList
      summary: Reference values with labels
      description: Value lists used in the API with labels in the requested language (`Accept-Language`).
      security:
      - ApiKey: []
      - OAuth2: []
      responses:
        '200':
          description: The list.
          content:
            application/json:
              schema:
                type: object
                required:
                - data
                properties:
                  data:
                    type: array
                    items:
                      type: object
                      required:
                      - value
                      - label
                      properties:
                        value:
                          type: string
                          examples:
                          - DE
                        label:
                          type: string
                          examples:
                          - Deutschland
                        meta:
                          type: object
                          additionalProperties: true
                          description: Extra data, e.g. the contribution rate of a health insurance fund.
        '401':
          $ref: '#/components/responses/Unauthorized'
  /batch:
    post:
      tags:
      - Batch
      operationId: batch
      summary: Run up to 20 requests in one call
      description: |
        Executes the requests in order and returns their responses. Each request counts against the rate
        limit. With `atomic: true` all write requests are rolled back if one fails.
      security:
      - ApiKey: []
      - OAuth2: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - requests
              properties:
                atomic:
                  type: boolean
                  default: false
                requests:
                  type: array
                  minItems: 1
                  maxItems: 20
                  items:
                    type: object
                    required:
                    - method
                    - path
                    properties:
                      id:
                        type: string
                        description: Your correlation ID.
                      method:
                        type: string
                        enum:
                        - GET
                        - POST
                        - PUT
                        - PATCH
                        - DELETE
                      path:
                        type: string
                        examples:
                        - /contacts/01a11123-2e86-713d-9536-4f9a063bab48
                      body:
                        type:
                        - object
                        - 'null'
                        additionalProperties: true
            example:
              atomic: true
              requests:
              - id: contact
                method: PUT
                path: /external/my-ams/contacts/K-100234
                body:
                  type: private
                  firstName: Manni
                  lastName: Mustermann
              - id: contract
                method: PUT
                path: /external/my-ams/contracts/V-55012
                body:
                  contactExternalReference:
                    source: my-ams
                    externalId: K-100234
                  type: liability
                  status: policy
      responses:
        '200':
          description: Responses in request order.
          content:
            application/json:
              schema:
                type: object
                required:
                - responses
                properties:
                  responses:
                    type: array
                    items:
                      type: object
                      required:
                      - status
                      properties:
                        id:
                          type:
                          - string
                          - 'null'
                        status:
                          type: integer
                        body:
                          type:
                          - object
                          - 'null'
                          additionalProperties: true
        '401':
          $ref: '#/components/responses/Unauthorized'
webhooks:
  event:
    post:
      tags:
      - Webhooks
      operationId: receiveEvent
      summary: Event notification (sent by Advision360 to your endpoint)
      description: |
        Advision360 sends one `POST` per event. Respond with `2xx` within 10 seconds; anything else
        counts as failure and is retried. Deliveries can arrive more than once and out of order:
        deduplicate by `Event.id` and compare `occurredAt`.

        **Signature:** `Advision360-Signature: t=<unix-seconds>,v1=<hex>` where `v1` is
        `HMAC-SHA256(secret, "<t>.<raw body>")`. Reject requests older than 5 minutes.
      parameters:
      - name: Advision360-Signature
        in: header
        required: true
        schema:
          type: string
          examples:
          - t=1792066200,v1=5257a869e7ecebeda32affa62cdca3fa51cad7e77a0e56ff536d0ce8e108d8bd
      - name: Advision360-Event-Type
        in: header
        required: true
        schema:
          $ref: '#/components/schemas/EventType'
      - name: Advision360-Delivery
        in: header
        required: true
        schema:
          $ref: '#/components/schemas/Uuid'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Event'
      responses:
        '200':
          description: Acknowledged.
components:
  securitySchemes:
    ApiKey:
      type: http
      scheme: bearer
      bearerFormat: sk_live_…
      description: Secret API key of a company. Never expose it in a browser or app.
    OAuth2:
      type: oauth2
      description: |
        For partner applications. Partner apps are registered by Advision360 as part of the activation;
        you then receive a client ID and the allowed redirect URIs.
        Access tokens live 1 hour, refresh tokens 90 days (rotating).
      flows:
        authorizationCode:
          authorizationUrl: https://app.advision360.de/oauth/authorize
          tokenUrl: https://app.advision360.de/oauth/token
          refreshUrl: https://app.advision360.de/oauth/token
          scopes:
            company:read: Company profile and settings needed for integrations.
            users:read: Team members of the company.
            contacts:read: Contacts incl. relationships, custom fields and timeline.
            contacts:write: Create, update, upsert and delete contacts.
            contacts.sensitive:read: Sensitive contact data (tax ID, social security number, ID documents, health, bank details, income).
            contacts.sensitive:write: Write sensitive contact data.
            leads:read: Leads and lead stages.
            leads:write: Create, update and convert leads.
            contracts:read: Contracts and the contract catalog.
            contracts:write: Create, update, upsert and change the status of contracts.
            documents:read: List and download documents.
            documents:write: Upload, update and delete documents.
            tasks:read: Tasks.
            tasks:write: Create and update tasks.
            appointments:read: Appointments.
            appointments:write: Create and update appointments.
            activities:read: Contact timeline.
            activities:write: Add notes and logged activities.
            correspondence:read: Insurer correspondence cases.
            correspondence:write: Start insurer correspondence.
            signatures:read: Signature requests and signed documents.
            signatures:write: Create and cancel signature requests.
            portal:write: Invite contacts to the customer portal.
            claims:read: Claims and their history.
            claims:write: Record claims, change their status and report them to insurers.
            commissions:read: Commission statements, entries and reports.
            commissions:write: Import statements and match entries.
            integrations:read: AMS and platform connections, sync runs and mappings.
            integrations:write: Connect systems, change mappings and start syncs.
            portfolio:read: Portfolio transfers and BiPRO deliveries.
            portfolio:write: Import GDV / BiPRO files and process deliveries.
            exports:write: Create data exports.
            imports:write: Import contacts from CSV or Excel.
            emails:read: Email threads and messages.
            emails:write: Send emails.
            marketing:read: Segments, funnels, landing pages and opt-outs.
            marketing:write: Enroll contacts in funnels and manage opt-outs.
            automations:read: Automations and their runs.
            automations:write: Start automations.
            calculators:read: Calculators and saved calculations.
            calculators:write: Create calculator launch links.
            offers:write: Start comparisons at connected platforms.
            advice:read: Advice documentation.
            advice:write: Document consultations.
            reports:read: Portfolio, pipeline and activity reports.
            privacy:write: Data subject access and erasure requests.
            admin:write: Custom fields, lead stages and tags.
            events:read: Event feed.
            webhooks:read: Webhook endpoints and deliveries.
            webhooks:write: Manage webhook endpoints.
        clientCredentials:
          tokenUrl: https://app.advision360.de/oauth/token
          scopes:
            company:read: Company profile and settings needed for integrations.
            users:read: Team members of the company.
            contacts:read: Contacts incl. relationships, custom fields and timeline.
            contacts:write: Create, update, upsert and delete contacts.
            contacts.sensitive:read: Sensitive contact data (tax ID, social security number, ID documents, health, bank details, income).
            contacts.sensitive:write: Write sensitive contact data.
            leads:read: Leads and lead stages.
            leads:write: Create, update and convert leads.
            contracts:read: Contracts and the contract catalog.
            contracts:write: Create, update, upsert and change the status of contracts.
            documents:read: List and download documents.
            documents:write: Upload, update and delete documents.
            tasks:read: Tasks.
            tasks:write: Create and update tasks.
            appointments:read: Appointments.
            appointments:write: Create and update appointments.
            activities:read: Contact timeline.
            activities:write: Add notes and logged activities.
            correspondence:read: Insurer correspondence cases.
            correspondence:write: Start insurer correspondence.
            signatures:read: Signature requests and signed documents.
            signatures:write: Create and cancel signature requests.
            portal:write: Invite contacts to the customer portal.
            claims:read: Claims and their history.
            claims:write: Record claims, change their status and report them to insurers.
            commissions:read: Commission statements, entries and reports.
            commissions:write: Import statements and match entries.
            integrations:read: AMS and platform connections, sync runs and mappings.
            integrations:write: Connect systems, change mappings and start syncs.
            portfolio:read: Portfolio transfers and BiPRO deliveries.
            portfolio:write: Import GDV / BiPRO files and process deliveries.
            exports:write: Create data exports.
            imports:write: Import contacts from CSV or Excel.
            emails:read: Email threads and messages.
            emails:write: Send emails.
            marketing:read: Segments, funnels, landing pages and opt-outs.
            marketing:write: Enroll contacts in funnels and manage opt-outs.
            automations:read: Automations and their runs.
            automations:write: Start automations.
            calculators:read: Calculators and saved calculations.
            calculators:write: Create calculator launch links.
            offers:write: Start comparisons at connected platforms.
            advice:read: Advice documentation.
            advice:write: Document consultations.
            reports:read: Portfolio, pipeline and activity reports.
            privacy:write: Data subject access and erasure requests.
            admin:write: Custom fields, lead stages and tags.
            events:read: Event feed.
            webhooks:read: Webhook endpoints and deliveries.
            webhooks:write: Manage webhook endpoints.
    PublishableKey:
      type: apiKey
      in: header
      name: X-API-Key
      description: Publishable `pk_live_` key. Only accepted by `POST /leads/intake`.
  parameters:
    Cursor:
      name: cursor
      in: query
      description: Opaque cursor from `pagination.nextCursor` of the previous page.
      schema:
        type: string
    Limit:
      name: limit
      in: query
      description: Page size.
      schema:
        type: integer
        minimum: 1
        maximum: 200
        default: 50
    UpdatedSince:
      name: updatedSince
      in: query
      description: Only return records changed at or after this timestamp.
      schema:
        type: string
        format: date-time
    Search:
      name: q
      in: query
      description: Full-text search.
      schema:
        type: string
        minLength: 2
    IdempotencyKey:
      name: Idempotency-Key
      in: header
      description: Makes a `POST` safely retryable for 24 hours.
      schema:
        type: string
        maxLength: 255
    IfMatch:
      name: If-Match
      in: header
      description: ETag of the version you modify. Mismatch returns `412`.
      schema:
        type: string
    ExternalSource:
      name: source
      in: path
      required: true
      description: Your system identifier, e.g. `my-crm`. Lowercase letters, digits and dashes.
      schema:
        type: string
        pattern: ^[a-z0-9][a-z0-9-]{1,63}$
    ExternalId:
      name: externalId
      in: path
      required: true
      description: The record ID in your system (URL-encoded).
      schema:
        type: string
        maxLength: 128
    ContactIdFilter:
      name: contactId
      in: query
      description: Only records of this contact.
      schema:
        type: string
        format: uuid
    AssigneeFilter:
      name: assigneeId
      in: query
      description: Only records assigned to this user.
      schema:
        type: string
        format: uuid
    ContactId:
      name: contactId
      in: path
      required: true
      schema:
        type: string
        format: uuid
    ContractId:
      name: contractId
      in: path
      required: true
      schema:
        type: string
        format: uuid
    DocumentId:
      name: documentId
      in: path
      required: true
      schema:
        type: string
        format: uuid
    CorrespondenceCaseId:
      name: caseId
      in: path
      required: true
      schema:
        type: string
        format: uuid
    SignatureRequestId:
      name: signatureRequestId
      in: path
      required: true
      schema:
        type: string
        format: uuid
    LeadId:
      name: leadId
      in: path
      required: true
      schema:
        type: string
        format: uuid
    TaskId:
      name: taskId
      in: path
      required: true
      schema:
        type: string
        format: uuid
    ConnectionId:
      name: connectionId
      in: path
      required: true
      schema:
        type: string
        format: uuid
    SyncRunId:
      name: runId
      in: path
      required: true
      schema:
        type: string
        format: uuid
    PortfolioTransferId:
      name: transferId
      in: path
      required: true
      schema:
        type: string
        format: uuid
    BiproDeliveryId:
      name: deliveryId
      in: path
      required: true
      schema:
        type: string
        format: uuid
    ClaimId:
      name: claimId
      in: path
      required: true
      schema:
        type: string
        format: uuid
    EmailId:
      name: emailId
      in: path
      required: true
      schema:
        type: string
        format: uuid
    FunnelId:
      name: funnelId
      in: path
      required: true
      schema:
        type: string
        format: uuid
    AutomationId:
      name: automationId
      in: path
      required: true
      schema:
        type: string
        format: uuid
    CalculatorSlug:
      name: slug
      in: path
      required: true
      schema:
        type: string
        examples:
        - rentenluecke
    AdviceRecordId:
      name: adviceRecordId
      in: path
      required: true
      schema:
        type: string
        format: uuid
    ImportId:
      name: importId
      in: path
      required: true
      schema:
        type: string
        format: uuid
  headers:
    RateLimitLimit:
      description: Requests allowed in the current window.
      schema:
        type: integer
    RateLimitRemaining:
      description: Requests left in the current window.
      schema:
        type: integer
    RateLimitReset:
      description: Seconds until the window resets.
      schema:
        type: integer
    ETag:
      description: Version tag of the returned resource.
      schema:
        type: string
    Location:
      description: URL of the created resource.
      schema:
        type: string
        format: uri
  responses:
    Unauthorized:
      description: Missing, invalid, revoked or expired credential.
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/Problem'
          example:
            type: https://app.advision360.de/api/public/problems/unauthorized
            title: Unauthorized
            status: 401
            detail: The API key is revoked.
    Forbidden:
      description: API access is not activated for the company, the credential lacks a scope, the license lacks the feature,
        or the acting user lacks the permission.
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/Problem'
          example:
            type: https://app.advision360.de/api/public/problems/insufficient-scope
            title: Insufficient scope
            status: 403
            detail: This request needs the scope contracts:write.
    NotFound:
      description: The resource does not exist or is not visible to the credential.
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/Problem'
    Conflict:
      description: The request conflicts with the current state (duplicate external reference, invalid status transition).
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/Problem'
    PreconditionFailed:
      description: '`If-Match` did not match the current ETag.'
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/Problem'
    ValidationFailed:
      description: One or more fields are invalid.
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/ValidationProblem'
          example:
            type: https://app.advision360.de/api/public/problems/validation-failed
            title: Validation failed
            status: 422
            errors:
            - field: email
              code: invalid_email
              message: This is not a valid email address.
            - field: address.zipCode
              code: too_long
              message: Use at most 10 characters.
    TooManyRequests:
      description: Rate limit exceeded.
      headers:
        Retry-After:
          description: Seconds to wait before retrying.
          schema:
            type: integer
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/Problem'
  schemas:
    Problem:
      type: object
      required:
      - type
      - title
      - status
      properties:
        type:
          type: string
          format: uri
        title:
          type: string
        status:
          type: integer
        detail:
          type: string
        instance:
          type: string
          description: Request ID, quote it when contacting support.
    ValidationProblem:
      allOf:
      - $ref: '#/components/schemas/Problem'
      - type: object
        required:
        - errors
        properties:
          errors:
            type: array
            items:
              type: object
              required:
              - field
              - code
              - message
              properties:
                field:
                  type: string
                  description: JSON path of the field, e.g. `phones[1].number`.
                code:
                  type: string
                  examples:
                  - required
                  - invalid_email
                  - too_long
                  - unknown_value
                message:
                  type: string
                  description: Human-readable, follows `Accept-Language`.
    Pagination:
      type: object
      required:
      - hasMore
      properties:
        nextCursor:
          type:
          - string
          - 'null'
        hasMore:
          type: boolean
    Uuid:
      type: string
      format: uuid
      examples:
      - 01a11123-2e86-713d-9536-4f9a063bab48
    Decimal:
      type: string
      pattern: ^-?\d+\.\d{2}$
      description: Decimal amount in EUR with two fraction digits.
      examples:
      - '112.00'
    Timestamps:
      type: object
      required:
      - createdAt
      - updatedAt
      properties:
        createdAt:
          type: string
          format: date-time
          readOnly: true
        updatedAt:
          type: string
          format: date-time
          readOnly: true
    ExternalReference:
      type: object
      required:
      - source
      - externalId
      properties:
        source:
          type: string
          pattern: ^[a-z0-9][a-z0-9-]{1,63}$
          examples:
          - my-crm
        externalId:
          type: string
          maxLength: 128
          examples:
          - K-100234
    UserRef:
      type: object
      required:
      - id
      - name
      properties:
        id:
          $ref: '#/components/schemas/Uuid'
        name:
          type: string
          examples:
          - Theo Testmakler
        email:
          type: string
          format: email
    CredentialContext:
      type: object
      required:
      - company
      - scopes
      - credentialType
      properties:
        credentialType:
          type: string
          enum:
          - api_key
          - oauth_user
          - oauth_client
        company:
          $ref: '#/components/schemas/CompanyRef'
        user:
          oneOf:
          - $ref: '#/components/schemas/UserRef'
          - type: 'null'
          description: Acting user. `null` for company-level keys and client-credentials tokens.
        scopes:
          type: array
          items:
            type: string
          examples:
          - - contacts:read
            - contracts:read
        expiresAt:
          type:
          - string
          - 'null'
          format: date-time
    CompanyRef:
      type: object
      required:
      - id
      - name
      properties:
        id:
          $ref: '#/components/schemas/Uuid'
        name:
          type: string
          examples:
          - Finakom Testmakler GmbH
    EventType:
      type: string
      enum:
      - ping
      - contact.created
      - contact.updated
      - contact.deleted
      - lead.created
      - lead.updated
      - lead.stage_changed
      - lead.converted
      - lead.deleted
      - contract.created
      - contract.updated
      - contract.status_changed
      - contract.deleted
      - document.created
      - document.updated
      - document.deleted
      - task.created
      - task.updated
      - task.completed
      - task.deleted
      - appointment.created
      - appointment.updated
      - appointment.deleted
      - activity.created
      - correspondence.sent
      - correspondence.status_changed
      - signature_request.sent
      - signature_request.signed
      - signature_request.completed
      - signature_request.declined
      - signature_request.expired
      - portal.invitation_accepted
      - portal.document_uploaded
      - portal.change_request_submitted
      - email.sent
      - email.received
      - email.bounced
      - claim.created
      - claim.updated
      - claim.status_changed
      - commission.statement_received
      - integration.sync_started
      - integration.sync_completed
      - integration.sync_failed
      - bipro.delivery_received
      - portfolio_transfer.validated
      - portfolio_transfer.completed
      - portfolio_transfer.failed
      - import.completed
      - export.completed
      - advice_record.created
      - automation.enrollment_completed
      - funnel.contact_unsubscribed
      - privacy_request.completed
    Event:
      type: object
      required:
      - id
      - type
      - occurredAt
      - companyId
      - data
      properties:
        id:
          $ref: '#/components/schemas/Uuid'
        type:
          $ref: '#/components/schemas/EventType'
        occurredAt:
          type: string
          format: date-time
        companyId:
          $ref: '#/components/schemas/Uuid'
        actor:
          description: Who caused the change. `null` for system and provider sync changes.
          oneOf:
          - type: object
            required:
            - type
            properties:
              type:
                type: string
                enum:
                - user
                - api
                - system
                - provider_sync
                - customer_portal
              user:
                $ref: '#/components/schemas/UserRef'
              credentialName:
                type: string
                description: Name of the API key or OAuth app.
          - type: 'null'
        data:
          type: object
          required:
          - object
          description: |
            The affected resource. For `*.deleted` only `id` and `externalReferences` are sent. For
            `*.updated` the full resource is sent plus `changedFields`.
          properties:
            object:
              type: object
              description: The resource in the same shape as its GET endpoint.
            changedFields:
              type: array
              items:
                type: string
              examples:
              - - email
                - address.city
    WebhookEndpointInput:
      type: object
      required:
      - url
      - eventTypes
      properties:
        url:
          type: string
          format: uri
          description: Must be HTTPS.
          examples:
          - https://crm.example.com/hooks/advision360
        description:
          type: string
          maxLength: 255
        eventTypes:
          type: array
          minItems: 1
          items:
            oneOf:
            - $ref: '#/components/schemas/EventType'
            - type: string
              const: '*'
          description: Event types to deliver. `*` means all events the credential may read.
        enabled:
          type: boolean
          default: true
    WebhookEndpointPatch:
      type: object
      minProperties: 1
      properties:
        url:
          type: string
          format: uri
        description:
          type: string
          maxLength: 255
        eventTypes:
          type: array
          minItems: 1
          items:
            type: string
        enabled:
          type: boolean
    WebhookEndpoint:
      allOf:
      - type: object
        required:
        - id
        - url
        - eventTypes
        - enabled
        - status
        properties:
          id:
            $ref: '#/components/schemas/Uuid'
          url:
            type: string
            format: uri
          description:
            type:
            - string
            - 'null'
          eventTypes:
            type: array
            items:
              type: string
          enabled:
            type: boolean
          status:
            type: string
            enum:
            - healthy
            - failing
            - disabled
            description: '`disabled` after 3 days of continuous failures; re-enable via PATCH.'
          lastDeliveryAt:
            type:
            - string
            - 'null'
            format: date-time
      - $ref: '#/components/schemas/Timestamps'
    WebhookDelivery:
      type: object
      required:
      - id
      - eventId
      - eventType
      - status
      - attempt
      - createdAt
      properties:
        id:
          $ref: '#/components/schemas/Uuid'
        eventId:
          $ref: '#/components/schemas/Uuid'
        eventType:
          $ref: '#/components/schemas/EventType'
        status:
          type: string
          enum:
          - succeeded
          - failed
          - pending
        attempt:
          type: integer
          description: 'Retries with exponential backoff: 1 min, 5 min, 30 min, 2 h, 6 h, 24 h.'
        responseStatus:
          type:
          - integer
          - 'null'
        responseTimeMs:
          type:
          - integer
          - 'null'
        error:
          type:
          - string
          - 'null'
        createdAt:
          type: string
          format: date-time
        nextAttemptAt:
          type:
          - string
          - 'null'
          format: date-time
    LicenseFeature:
      type: string
      enum:
      - contacts
      - leads
      - tasks
      - calendar
      - mailbox
      - email_marketing
      - automations
      - customer_portal
      - digital_signature
      - integrations
      - holding
      - fnb
      - mrmoney
      - nafi
      - codie_finakom
      - professional_works
      - german_broker
      - bipro_stuttgarter
      - liechtenstein_life
      - pdf_box
      - cms
      - social_media
      - email_marketing_ai
      - public_api
    Company:
      type: object
      required:
      - id
      - name
      - features
      properties:
        id:
          $ref: '#/components/schemas/Uuid'
        name:
          type: string
        address:
          type: object
          properties:
            street:
              type:
              - string
              - 'null'
            houseNumber:
              type:
              - string
              - 'null'
            zipCode:
              type:
              - string
              - 'null'
            city:
              type:
              - string
              - 'null'
        logoUrl:
          type:
          - string
          - 'null'
          format: uri
        links:
          type: object
          properties:
            homepage:
              type:
              - string
              - 'null'
              format: uri
            booking:
              type:
              - string
              - 'null'
              format: uri
              description: Online booking link of the broker.
            privacyPolicy:
              type:
              - string
              - 'null'
              format: uri
            imprint:
              type:
              - string
              - 'null'
              format: uri
            initialInformation:
              type:
              - string
              - 'null'
              format: uri
              description: Erstinformation according to § 15 VersVermV.
        features:
          type: array
          items:
            $ref: '#/components/schemas/LicenseFeature'
        holding:
          type:
          - object
          - 'null'
          description: Set when the company belongs to a group of companies.
          properties:
            id:
              $ref: '#/components/schemas/Uuid'
            name:
              type: string
            isLeadingCompany:
              type: boolean
    User:
      type: object
      required:
      - id
      - email
      - firstName
      - lastName
      - status
      properties:
        id:
          $ref: '#/components/schemas/Uuid'
        email:
          type: string
          format: email
        salutation:
          type:
          - string
          - 'null'
          enum:
          - mr
          - mrs
          - diverse
          - null
        firstName:
          type: string
        lastName:
          type: string
        phone:
          type:
          - string
          - 'null'
        status:
          type: string
          enum:
          - active
          - inactive
          - suspended
        role:
          type: object
          required:
          - id
          - name
          properties:
            id:
              $ref: '#/components/schemas/Uuid'
            name:
              type: string
              examples:
              - Inhaber
        avatarUrl:
          type:
          - string
          - 'null'
          format: uri
        createdAt:
          type: string
          format: date-time
    ContactType:
      type: string
      enum:
      - private
      - business
    ContactRelationshipRole:
      type: string
      enum:
      - partner
      - child
      - parent
      - employer
      - employee
    LabelColor:
      type: string
      enum:
      - red
      - blue
      - green
      - yellow
      - orange
      - purple
      - pink
      - cyan
      - gray
      - brown
    CountryCode:
      type: string
      pattern: ^[A-Z]{2}$
      description: ISO 3166-1 alpha-2.
      examples:
      - DE
    Phone:
      type: object
      required:
      - id
      - type
      - number
      - isPrimary
      properties:
        id:
          $ref: '#/components/schemas/Uuid'
        type:
          type: string
          enum:
          - mobile
          - landline
          - work
          - fax
        number:
          type: string
          description: E.164.
          examples:
          - '+491775935467'
        originalNumber:
          type: string
          examples:
          - 0177 5935467
        countryCode:
          $ref: '#/components/schemas/CountryCode'
        isPrimary:
          type: boolean
    PhoneInput:
      type: object
      required:
      - number
      properties:
        number:
          type: string
          minLength: 5
          maxLength: 50
          description: Any format; German numbers without country code are assumed.
        type:
          type: string
          enum:
          - mobile
          - landline
          - work
          - fax
          default: mobile
        isPrimary:
          type: boolean
          default: false
    Address:
      type: object
      properties:
        street:
          type:
          - string
          - 'null'
          maxLength: 255
        houseNumber:
          type:
          - string
          - 'null'
          maxLength: 20
        zipCode:
          type:
          - string
          - 'null'
          maxLength: 10
        city:
          type:
          - string
          - 'null'
          maxLength: 100
        country:
          oneOf:
          - $ref: '#/components/schemas/CountryCode'
          - type: 'null'
    PersonalFields:
      type: object
      description: Private contacts only.
      properties:
        salutation:
          type:
          - string
          - 'null'
          enum:
          - mr
          - mrs
          - diverse
          - null
        gender:
          type:
          - string
          - 'null'
          enum:
          - male
          - female
          - diverse
          - null
        title:
          type:
          - string
          - 'null'
          maxLength: 50
          examples:
          - Dr.
        dateOfBirth:
          type:
          - string
          - 'null'
          format: date
        birthPlace:
          type:
          - string
          - 'null'
          maxLength: 255
        countryOfBirth:
          oneOf:
          - $ref: '#/components/schemas/CountryCode'
          - type: 'null'
        nationality:
          oneOf:
          - $ref: '#/components/schemas/CountryCode'
          - type: 'null'
        maritalStatus:
          type:
          - string
          - 'null'
          enum:
          - single
          - married
          - cohabitation
          - separated
          - divorced
          - widowed
          - null
        lifeSituation:
          type:
          - string
          - 'null'
          enum:
          - family_with_child
          - partnership_without_child
          - single_parent
          - single
          - null
    HealthFields:
      type: object
      description: Private contacts only. Needs `contacts.sensitive:read`.
      properties:
        smoker:
          type:
          - boolean
          - 'null'
        height:
          type:
          - integer
          - 'null'
          minimum: 0
          maximum: 300
          description: Centimetres.
        weight:
          type:
          - integer
          - 'null'
          minimum: 0
          maximum: 1000
          description: Kilograms.
    ProfessionFields:
      type: object
      description: Private contacts only.
      properties:
        employmentStatus:
          type:
          - string
          - 'null'
          enum:
          - employed
          - self_employed
          - freelancer
          - student
          - retired
          - unemployed
          - null
        profession:
          type:
          - string
          - 'null'
          maxLength: 100
        civilServantStatus:
          type:
          - string
          - 'null'
          enum:
          - life_tenure
          - probation
          - revocation
          - null
        employmentMode:
          type:
          - string
          - 'null'
          enum:
          - full_time
          - part_time
          - marginal
          - seasonal
          - null
        staffResponsibility:
          type:
          - integer
          - 'null'
          minimum: 0
          description: Number of employees led.
        educationLevel:
          type:
          - string
          - 'null'
          enum:
          - completed_studies
          - abitur
          - fachabitur
          - secondary_school
          - lower_secondary
          - no_degree
          - null
        academicDegree:
          type:
          - string
          - 'null'
          maxLength: 255
        professionalTraining:
          type:
          - string
          - 'null'
          enum:
          - completed_apprenticeship
          - completed_studies
          - master_craftsman
          - technician
          - business_administrator
          - none
          - null
        professionalTrainingDefinition:
          type:
          - string
          - 'null'
          enum:
          - commercial
          - craft
          - industrial
          - short_training
          - other
          - null
        physicalWorkPercent:
          type:
          - integer
          - 'null'
          minimum: 0
          maximum: 100
        officeWorkPercent:
          type:
          - integer
          - 'null'
          minimum: 0
          maximum: 100
        businessTravelPercent:
          type:
          - integer
          - 'null'
          minimum: 0
          maximum: 100
        salaryGrade:
          type:
          - string
          - 'null'
          maxLength: 100
          examples:
          - A 13
    BankFields:
      type: object
      description: Private contacts only. Needs `contacts.sensitive:read`.
      properties:
        accountHolder:
          type:
          - string
          - 'null'
          maxLength: 255
        iban:
          type:
          - string
          - 'null'
          maxLength: 34
          examples:
          - DE02120300000000202051
        bic:
          type:
          - string
          - 'null'
          maxLength: 11
        bankName:
          type:
          - string
          - 'null'
          maxLength: 255
    IncomeFields:
      type: object
      description: Private contacts only. Whole euros per year. Needs `contacts.sensitive:read`.
      properties:
        grossAnnualIncome:
          type:
          - integer
          - 'null'
          minimum: 0
          maximum: 100000000
        netAnnualIncome:
          type:
          - integer
          - 'null'
          minimum: 0
          maximum: 100000000
    IdentityFields:
      type: object
      description: Encrypted at rest. Private contacts only. Needs `contacts.sensitive:read` / `:write`.
      properties:
        taxIdentificationNumber:
          type:
          - string
          - 'null'
          description: Steuer-ID.
        socialInsuranceNumber:
          type:
          - string
          - 'null'
          description: Sozialversicherungsnummer.
        identityCardNumber:
          type:
          - string
          - 'null'
        identityCardIssuedOn:
          type:
          - string
          - 'null'
          format: date
        identityCardExpiryDate:
          type:
          - string
          - 'null'
          format: date
        identityCardIssuingAuthority:
          type:
          - string
          - 'null'
    SocialTaxFields:
      type: object
      description: Private contacts only.
      properties:
        taxClass:
          type:
          - string
          - 'null'
          enum:
          - i
          - ii
          - iii
          - iv
          - v
          - vi
          - null
        confession:
          type:
          - string
          - 'null'
          enum:
          - roman_catholic
          - protestant
          - old_catholic
          - jewish
          - none
          - other
          - null
        taxOffice:
          type:
          - string
          - 'null'
        taxNumber:
          type:
          - string
          - 'null'
        childAllowances:
          type:
          - number
          - 'null'
          examples:
          - 1.5
        churchTaxLiable:
          type:
          - boolean
          - 'null'
        jointAssessment:
          type:
          - boolean
          - 'null'
        healthInsuranceType:
          type:
          - string
          - 'null'
          enum:
          - gkv
          - voluntary_gkv
          - pkv
          - null
        healthInsuranceFundKey:
          type:
          - string
          - 'null'
          enum:
          - tk
          - barmer
          - dak
          - aok_bayern
          - aok_bw
          - aok_nordost
          - aok_rheinland_hamburg
          - aok_plus
          - ikk_classic
          - kkh
          - hkk
          - knappschaft
          - bkk_vbu
          - sbk
          - other
          - null
        additionalContribution:
          type:
          - number
          - 'null'
          description: Additional contribution rate in percent.
        manualFundName:
          type:
          - string
          - 'null'
          description: Fund name when `healthInsuranceFundKey` is `other`.
        privateInsurerName:
          type:
          - string
          - 'null'
        unemploymentInsuranceLiable:
          type:
          - boolean
          - 'null'
        careSurchargeChildless:
          type:
          - boolean
          - 'null'
    PensionFields:
      type: object
      description: Statutory pension data of a private contact.
      properties:
        pensionStatus:
          type:
          - string
          - 'null'
          enum:
          - mandatory
          - voluntary
          - exempt
          - not_insured
          - null
        pensionInsuranceNumber:
          type:
          - string
          - 'null'
        earningPoints:
          type:
          - number
          - 'null'
        currentPension:
          type:
          - number
          - 'null'
          description: EUR per month.
        projectedStandardPension:
          type:
          - number
          - 'null'
          description: EUR per month.
        fullReductionPension:
          type:
          - number
          - 'null'
          description: EUR per month.
        plannedRetirementAge:
          type:
          - integer
          - 'null'
          minimum: 40
          maximum: 80
        pensionInfoDate:
          type:
          - string
          - 'null'
          format: date
    BusinessFields:
      type: object
      description: Business contacts only.
      properties:
        companyName:
          type:
          - string
          - 'null'
          maxLength: 255
        legalForm:
          type:
          - string
          - 'null'
          enum:
          - sole_proprietorship
          - gbr
          - ohg
          - kg
          - gmbh
          - ug
          - ag
          - gmbh_co_kg
          - registered_association
          - null
    CustomFieldValues:
      type: object
      description: Values of the company's custom fields keyed by `CustomFieldDefinition.key`. `null` removes a value.
      additionalProperties:
        type:
        - string
        - number
        - boolean
        - array
        - 'null'
        items:
          type: string
      examples:
      - tippgeber: Autohaus Schmidt
        kundenwert: 3
        vip: true
    ContactFieldGroups:
      type: object
      properties:
        address:
          $ref: '#/components/schemas/Address'
        personal:
          $ref: '#/components/schemas/PersonalFields'
        health:
          $ref: '#/components/schemas/HealthFields'
        profession:
          $ref: '#/components/schemas/ProfessionFields'
        bank:
          $ref: '#/components/schemas/BankFields'
        income:
          $ref: '#/components/schemas/IncomeFields'
        identity:
          $ref: '#/components/schemas/IdentityFields'
        socialTax:
          $ref: '#/components/schemas/SocialTaxFields'
        pension:
          $ref: '#/components/schemas/PensionFields'
        business:
          $ref: '#/components/schemas/BusinessFields'
    ContactCoreWritable:
      type: object
      properties:
        firstName:
          type:
          - string
          - 'null'
          maxLength: 100
          description: Private person, or the contact person of a business.
        lastName:
          type:
          - string
          - 'null'
          maxLength: 100
        email:
          type:
          - string
          - 'null'
          format: email
          maxLength: 255
        ownerId:
          type:
          - string
          - 'null'
          format: uuid
          description: User who looks after the contact.
        tags:
          type: array
          description: Tag names; unknown tags are created.
          items:
            type: string
            maxLength: 50
        labels:
          type: array
          items:
            $ref: '#/components/schemas/LabelColor'
        customFields:
          $ref: '#/components/schemas/CustomFieldValues'
        externalReferences:
          type: array
          items:
            $ref: '#/components/schemas/ExternalReference'
    ContactCreate:
      allOf:
      - type: object
        required:
        - type
        properties:
          type:
            $ref: '#/components/schemas/ContactType'
          phones:
            type: array
            maxItems: 10
            items:
              $ref: '#/components/schemas/PhoneInput'
      - $ref: '#/components/schemas/ContactCoreWritable'
      - $ref: '#/components/schemas/ContactFieldGroups'
    ContactUpsert:
      allOf:
      - $ref: '#/components/schemas/ContactCreate'
      - type: object
        properties:
          writeMode:
            $ref: '#/components/schemas/WriteMode'
    ContactPatch:
      allOf:
      - type: object
        properties:
          writeMode:
            $ref: '#/components/schemas/WriteMode'
      - $ref: '#/components/schemas/ContactCoreWritable'
      - $ref: '#/components/schemas/ContactFieldGroups'
    WriteMode:
      type: string
      enum:
      - overwrite
      - fill_empty_only
      default: overwrite
    ContactSummary:
      type: object
      required:
      - id
      - type
      - displayName
      properties:
        id:
          $ref: '#/components/schemas/Uuid'
        type:
          $ref: '#/components/schemas/ContactType'
        displayName:
          type: string
          examples:
          - Manni Mustermann
        email:
          type:
          - string
          - 'null'
          format: email
        city:
          type:
          - string
          - 'null'
        dateOfBirth:
          type:
          - string
          - 'null'
          format: date
    Contact:
      allOf:
      - type: object
        required:
        - id
        - type
        - displayName
        - phones
        - tags
        - labels
        - customFields
        - externalReferences
        - source
        - portalAccessStatus
        properties:
          id:
            $ref: '#/components/schemas/Uuid'
          type:
            $ref: '#/components/schemas/ContactType'
          displayName:
            type: string
            readOnly: true
            description: Company name for businesses, otherwise title, first and last name.
            examples:
            - Manni Mustermann
          phones:
            type: array
            items:
              $ref: '#/components/schemas/Phone'
          owner:
            oneOf:
            - $ref: '#/components/schemas/UserRef'
            - type: 'null'
          source:
            type: object
            readOnly: true
            required:
            - type
            properties:
              type:
                type: string
                enum:
                - manual
                - api
                - csv_import
                - lead_conversion
                - provider_sync
              provider:
                type:
                - string
                - 'null'
                description: Provider key for `provider_sync`, e.g. `codie_finakom`.
              providerLabel:
                type:
                - string
                - 'null'
                examples:
                - CODie (via Finakom-Middleware)
              lastSyncedAt:
                type:
                - string
                - 'null'
                format: date-time
          portalAccessStatus:
            type: string
            readOnly: true
            enum:
            - none
            - pending
            - active
            - revoked
          relationships:
            type: array
            description: Only with `expand=relationships`.
            items:
              $ref: '#/components/schemas/ContactRelationship'
      - $ref: '#/components/schemas/ContactCoreWritable'
      - $ref: '#/components/schemas/ContactFieldGroups'
      - $ref: '#/components/schemas/Timestamps'
    ContactRelationship:
      type: object
      required:
      - id
      - role
      - relatedContact
      properties:
        id:
          $ref: '#/components/schemas/Uuid'
        role:
          $ref: '#/components/schemas/ContactRelationshipRole'
        relatedContact:
          $ref: '#/components/schemas/ContactSummary'
        position:
          type:
          - string
          - 'null'
          examples:
          - Geschäftsführerin
        createdAt:
          type: string
          format: date-time
    FinanceItemBase:
      type: object
      properties:
        id:
          $ref: '#/components/schemas/Uuid'
        label:
          type: string
          maxLength: 255
    ContactFinance:
      type: object
      required:
      - incomes
      - expenses
      - assets
      - liabilities
      - realEstate
      - totals
      properties:
        incomes:
          type: array
          items:
            $ref: '#/components/schemas/FinanceFlowItem'
        expenses:
          type: array
          items:
            $ref: '#/components/schemas/FinanceFlowItem'
        assets:
          type: array
          items:
            $ref: '#/components/schemas/AssetItem'
        liabilities:
          type: array
          items:
            $ref: '#/components/schemas/LiabilityItem'
        realEstate:
          type: array
          items:
            $ref: '#/components/schemas/RealEstateItem'
        totals:
          type: object
          readOnly: true
          properties:
            monthlyIncome:
              $ref: '#/components/schemas/Decimal'
            monthlyExpenses:
              $ref: '#/components/schemas/Decimal'
            monthlySurplus:
              $ref: '#/components/schemas/Decimal'
            totalAssets:
              $ref: '#/components/schemas/Decimal'
            totalLiabilities:
              $ref: '#/components/schemas/Decimal'
            netWorth:
              $ref: '#/components/schemas/Decimal'
        updatedAt:
          type:
          - string
          - 'null'
          format: date-time
    ContactFinanceInput:
      type: object
      minProperties: 1
      properties:
        incomes:
          type: array
          items:
            $ref: '#/components/schemas/FinanceFlowItem'
        expenses:
          type: array
          items:
            $ref: '#/components/schemas/FinanceFlowItem'
        assets:
          type: array
          items:
            $ref: '#/components/schemas/AssetItem'
        liabilities:
          type: array
          items:
            $ref: '#/components/schemas/LiabilityItem'
        realEstate:
          type: array
          items:
            $ref: '#/components/schemas/RealEstateItem'
    FinanceFlowItem:
      allOf:
      - $ref: '#/components/schemas/FinanceItemBase'
      - type: object
        required:
        - category
        - amount
        - interval
        properties:
          category:
            type: string
            description: 'Incomes: salary, self_employment, pension, rental, capital, child_benefit, alimony, social_benefits,
              other. Expenses: housing, utilities, living, mobility, insurance, loans, savings, leisure, children, health,
              other.'
          amount:
            $ref: '#/components/schemas/Decimal'
          interval:
            type: string
            enum:
            - monthly
            - quarterly
            - semi_annual
            - annual
    AssetItem:
      allOf:
      - $ref: '#/components/schemas/FinanceItemBase'
      - type: object
        required:
        - category
        - value
        properties:
          category:
            type: string
            enum:
            - bank_account
            - savings_deposit
            - securities
            - building_savings
            - life_insurance
            - vehicle
            - precious_metals
            - business_share
            - other
          value:
            $ref: '#/components/schemas/Decimal'
    LiabilityItem:
      allOf:
      - $ref: '#/components/schemas/FinanceItemBase'
      - type: object
        required:
        - type
        - remainingDebt
        properties:
          type:
            type: string
            enum:
            - real_estate_loan
            - installment_loan
            - overdraft
            - leasing
            - private_loan
            - tax_debt
            - other
          remainingDebt:
            $ref: '#/components/schemas/Decimal'
          monthlyRate:
            oneOf:
            - $ref: '#/components/schemas/Decimal'
            - type: 'null'
          interestRate:
            type:
            - number
            - 'null'
            description: Percent per year.
          remainingTermYears:
            type:
            - number
            - 'null'
          note:
            type:
            - string
            - 'null'
    RealEstateItem:
      allOf:
      - $ref: '#/components/schemas/FinanceItemBase'
      - type: object
        required:
        - objectType
        - usage
        properties:
          objectType:
            type: string
            enum:
            - detached_house
            - semi_detached_house
            - terraced_house
            - condominium
            - apartment_building
            - land
            - commercial
            - other
          usage:
            type: string
            enum:
            - owner_occupied
            - rented
            - partially_rented
            - commercial
            - undeveloped
          address:
            $ref: '#/components/schemas/Address'
          constructionYear:
            type:
            - integer
            - 'null'
          livingArea:
            type:
            - number
            - 'null'
            description: Square metres.
          marketValue:
            oneOf:
            - $ref: '#/components/schemas/Decimal'
            - type: 'null'
          remainingDebt:
            oneOf:
            - $ref: '#/components/schemas/Decimal'
            - type: 'null'
          rentalIncome:
            oneOf:
            - $ref: '#/components/schemas/Decimal'
            - type: 'null'
          note:
            type:
            - string
            - 'null'
          building:
            type:
            - object
            - 'null'
            description: Building details used for building insurance quotes (construction class, roof, basement, quality
              levels, renovations).
            properties:
              buildingType:
                type:
                - string
                - 'null'
                enum:
                - single_family
                - two_family
                - apartment_building
                - null
              constructionClass:
                type:
                - string
                - 'null'
                enum:
                - class_1
                - class_2
                - class_3
                - class_4a
                - class_4b
                - class_5
                - class_f1
                - class_f2
                - class_f3
                - null
              floors:
                type:
                - integer
                - 'null'
              roofType:
                type:
                - string
                - 'null'
                enum:
                - flat
                - pitched_unconverted
                - pitched_converted
                - null
              hasBasement:
                type:
                - boolean
                - 'null'
              residentialUnits:
                type:
                - integer
                - 'null'
              garageCount:
                type:
                - integer
                - 'null'
              heritageProtection:
                type:
                - boolean
                - 'null'
              photovoltaic:
                type:
                - boolean
                - 'null'
              renovations:
                type: array
                items:
                  type: object
                  required:
                  - area
                  - done
                  properties:
                    area:
                      type: string
                      enum:
                      - electric
                      - water_pipes
                      - supply_pipes
                      - drain_pipes
                      - sanitary
                      - heating
                      - heating_system
                      - heating_pipes
                      - roof
                      - roof_frame
                      - roof_covering
                      - facade
                      - interior
                    done:
                      type: boolean
                    year:
                      type:
                      - integer
                      - 'null'
    ActivityType:
      type: string
      enum:
      - note
      - email_in
      - email_out
      - contact_created
      - contact_updated
      - lead_converted
      - contract_created
      - contract_updated
      - contract_deleted
      - phone_added
      - phone_updated
      - phone_deleted
      - tags_changed
      - labels_changed
      - relationship_created
      - relationship_deleted
      - task_created
      - task_completed
      - task_assignee_changed
      - task_due_date_changed
      - task_deleted
      - document_uploaded
      - document_linked_to_contract
      - document_deleted
      - portal_calculation_saved
    Activity:
      type: object
      required:
      - id
      - contactId
      - type
      - createdAt
      properties:
        id:
          $ref: '#/components/schemas/Uuid'
        contactId:
          $ref: '#/components/schemas/Uuid'
        type:
          $ref: '#/components/schemas/ActivityType'
        content:
          type:
          - string
          - 'null'
          description: Note text, email preview or a system message.
        author:
          oneOf:
          - $ref: '#/components/schemas/UserRef'
          - type: 'null'
        related:
          type:
          - object
          - 'null'
          description: The object the entry is about.
          properties:
            type:
              type: string
              enum:
              - contract
              - document
              - task
              - email
              - relationship
              - lead
            id:
              $ref: '#/components/schemas/Uuid'
        externalReferences:
          type: array
          items:
            $ref: '#/components/schemas/ExternalReference'
        occurredAt:
          type: string
          format: date-time
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type:
          - string
          - 'null'
          format: date-time
    PortalAccess:
      type: object
      required:
      - status
      properties:
        status:
          type: string
          enum:
          - none
          - pending
          - active
          - revoked
        email:
          type:
          - string
          - 'null'
          format: email
        invitedAt:
          type:
          - string
          - 'null'
          format: date-time
        activatedAt:
          type:
          - string
          - 'null'
          format: date-time
        lastLoginAt:
          type:
          - string
          - 'null'
          format: date-time
    PortalChangeRequest:
      type: object
      required:
      - id
      - contactId
      - section
      - status
      - requestedValues
      - createdAt
      properties:
        id:
          $ref: '#/components/schemas/Uuid'
        contactId:
          $ref: '#/components/schemas/Uuid'
        section:
          type: string
          enum:
          - name
          - dateOfBirth
          - maritalStatus
          - address
          - email
          - phone
        status:
          type: string
          enum:
          - pending
          - approved
          - rejected
          - withdrawn
        currentValues:
          type: object
          additionalProperties: true
        requestedValues:
          type: object
          additionalProperties: true
          examples:
          - street: Neue Straße
            houseNumber: '1'
            zipCode: '04109'
            city: Leipzig
        decidedBy:
          oneOf:
          - $ref: '#/components/schemas/UserRef'
          - type: 'null'
        decidedAt:
          type:
          - string
          - 'null'
          format: date-time
        createdAt:
          type: string
          format: date-time
    ContactFieldDefinition:
      type: object
      required:
      - key
      - group
      - type
      - label
      - contactTypes
      - sensitive
      properties:
        key:
          type: string
          examples:
          - maritalStatus
        group:
          type: string
          enum:
          - address
          - personal
          - health
          - profession
          - bank
          - income
          - identity
          - business
          - socialTax
          - pension
        type:
          type: string
          enum:
          - string
          - number
          - boolean
          - date
          - enum
          - country
        label:
          type: string
          description: English field name. Option labels follow `Accept-Language`.
          examples:
          - Marital Status
        description:
          type:
          - string
          - 'null'
        contactTypes:
          type: array
          items:
            $ref: '#/components/schemas/ContactType'
        options:
          type: array
          description: Only for `enum`.
          items:
            $ref: '#/components/schemas/LabeledValue'
        format:
          type:
          - string
          - 'null'
          enum:
          - currency
          - percent
          - null
        validation:
          type: object
          properties:
            maxLength:
              type: integer
            min:
              type: number
            max:
              type: number
        sensitive:
          type: boolean
          description: Needs the `contacts.sensitive` scopes.
        visibleInCompany:
          type: boolean
          description: Whether the company shows the field on the contact page. Hidden fields stay readable and writable.
    CustomFieldDefinition:
      type: object
      required:
      - id
      - key
      - label
      - type
      - contactTypes
      - required
      properties:
        id:
          $ref: '#/components/schemas/Uuid'
        key:
          type: string
          examples:
          - tippgeber
        label:
          type: string
          examples:
          - Tippgeber
        type:
          type: string
          enum:
          - string
          - number
          - date
          - boolean
          - select
          - multiselect
        contactTypes:
          type: array
          items:
            $ref: '#/components/schemas/ContactType'
        required:
          type: boolean
        options:
          type: array
          items:
            type: string
        validation:
          type: object
          properties:
            min:
              type: number
            max:
              type: number
            minLength:
              type: integer
            maxLength:
              type: integer
            pattern:
              type: string
        category:
          type:
          - string
          - 'null'
    BulkResult:
      type: object
      required:
      - data
      properties:
        data:
          type: array
          items:
            type: object
            required:
            - index
            - status
            properties:
              index:
                type: integer
                description: Position in the request.
              status:
                type: string
                enum:
                - created
                - updated
                - unchanged
                - failed
              id:
                type:
                - string
                - 'null'
                format: uuid
              error:
                oneOf:
                - $ref: '#/components/schemas/ValidationProblem'
                - type: 'null'
    ContractType:
      type: string
      enum:
      - vehicle
      - health
      - supplementary_health
      - life
      - pension
      - disability
      - occupational_disability
      - basic_disability
      - accident
      - long_term_care
      - statutory_pension
      - liability
      - property_owner_liability
      - legal_protection
      - household_contents
      - building
      - pet_liability
      - pet_health
      - business_liability
      - professional_liability
      - financial_loss_liability
      - business_contents
      - cyber_insurance
      - business_interruption
      - transport_insurance
      - directors_officers
      - investment
      - bank_account
      - building_savings
      - loan
      - real_estate
      - participation
      - other
    ContractTypeGroup:
      type: string
      enum:
      - mobility
      - health_provision
      - liability_legal
      - property
      - pets
      - business
      - finance
      - other
    ContractStatus:
      type: string
      description: |
        `draft`, `offer`, `application` are pipeline statuses; `policy`, `dormant`, `terminated` have
        coverage; `cancelled`, `lost`, `transferred_out` are closed.
      enum:
      - draft
      - offer
      - application
      - policy
      - dormant
      - terminated
      - cancelled
      - lost
      - transferred_out
    ContractCoverage:
      type: string
      description: Computed from status and dates. Only set for `policy`, `dormant` and `terminated`.
      enum:
      - scheduled
      - active
      - expired
    PaymentFrequency:
      type: string
      enum:
      - monthly
      - quarterly
      - semi_annual
      - annual
      - one_time
    ContractSource:
      type: string
      description: Where the contract came from. `fnb`, `provider_sync`, `mrmoney` and `nafi` are provider-managed.
      enum:
      - api
      - manual
      - contact_import
      - extraction
      - provider_sync
      - fnb
      - mrmoney
      - nafi
      - bipro
    ContractAction:
      type: string
      enum:
      - submit_application
      - convert_to_policy
      - mark_lost
      - suspend
      - reactivate
      - terminate
      - cancel
      - transfer_out
      - reopen
      - reopen_lost
    ContractInsurerInput:
      type: object
      description: Either a catalog entry (`insurerId`) or a free-text `name`.
      properties:
        insurerId:
          type:
          - string
          - 'null'
          format: uuid
        name:
          type:
          - string
          - 'null'
          maxLength: 255
    ContractPremiumInput:
      type: object
      properties:
        gross:
          $ref: '#/components/schemas/Decimal'
        net:
          oneOf:
          - $ref: '#/components/schemas/Decimal'
          - type: 'null'
        paymentFrequency:
          $ref: '#/components/schemas/PaymentFrequency'
    TypeSpecificData:
      type: object
      description: |
        Values of the type-specific fields, keyed by field `key` from `GET /contract-types/{type}`.
        Unknown keys are rejected. Dates as `YYYY-MM-DD`, selects by option `value`.
      additionalProperties:
        type:
        - string
        - number
        - boolean
        - 'null'
      examples:
      - coverageAmount: 10000000
        tariffType: family
        keyLossCoverage: true
    ContractWritable:
      type: object
      properties:
        insurer:
          $ref: '#/components/schemas/ContractInsurerInput'
        policyNumber:
          type:
          - string
          - 'null'
          maxLength: 100
        premium:
          $ref: '#/components/schemas/ContractPremiumInput'
        startDate:
          type:
          - string
          - 'null'
          format: date
        endDate:
          type:
          - string
          - 'null'
          format: date
        insuredSum:
          type:
          - string
          - 'null'
          maxLength: 500
          description: Free text, e.g. "10 Mio. EUR pauschal".
        notes:
          type:
          - string
          - 'null'
          maxLength: 5000
        typeSpecificData:
          $ref: '#/components/schemas/TypeSpecificData'
        externalReferences:
          type: array
          items:
            $ref: '#/components/schemas/ExternalReference'
    ContractCreate:
      allOf:
      - type: object
        required:
        - contactId
        - type
        properties:
          contactId:
            $ref: '#/components/schemas/Uuid'
          type:
            $ref: '#/components/schemas/ContractType'
          status:
            type: string
            enum:
            - offer
            - application
            - policy
            default: policy
      - $ref: '#/components/schemas/ContractWritable'
    ContractUpsert:
      allOf:
      - type: object
        required:
        - type
        properties:
          contactId:
            $ref: '#/components/schemas/Uuid'
          contactExternalReference:
            $ref: '#/components/schemas/ExternalReference'
          type:
            $ref: '#/components/schemas/ContractType'
          status:
            type: string
            enum:
            - offer
            - application
            - policy
            - dormant
            - terminated
            - cancelled
            - transferred_out
            description: Target status. Applied through the regular transitions; impossible jumps return `409`.
      - $ref: '#/components/schemas/ContractWritable'
    ContractPatch:
      allOf:
      - type: object
        properties:
          type:
            $ref: '#/components/schemas/ContractType'
      - $ref: '#/components/schemas/ContractWritable'
    ContractAllowedAction:
      type: object
      required:
      - action
      - enabled
      properties:
        action:
          $ref: '#/components/schemas/ContractAction'
        label:
          type: string
          examples:
          - Kündigen
        enabled:
          type: boolean
        requiresEndDate:
          type: boolean
        missingFields:
          type: array
          description: Fields that must be filled before the action is enabled.
          items:
            type: string
          examples:
          - - policyNumber
            - premium.gross
    Contract:
      allOf:
      - type: object
        required:
        - id
        - contactId
        - type
        - typeGroup
        - status
        - source
        - providerManaged
        - premium
        - insurer
        - typeSpecificData
        - externalReferences
        - allowedActions
        properties:
          id:
            $ref: '#/components/schemas/Uuid'
          contactId:
            $ref: '#/components/schemas/Uuid'
          type:
            $ref: '#/components/schemas/ContractType'
          typeLabel:
            type: string
            readOnly: true
            examples:
            - Haftpflichtversicherung
          typeGroup:
            $ref: '#/components/schemas/ContractTypeGroup'
          insurer:
            type: object
            required:
            - name
            properties:
              insurerId:
                type:
                - string
                - 'null'
                format: uuid
              name:
                type:
                - string
                - 'null'
                examples:
                - VHV Allgemeine Versicherung AG
          policyNumber:
            type:
            - string
            - 'null'
          premium:
            type: object
            required:
            - gross
            - net
            - paymentFrequency
            - annual
            properties:
              gross:
                oneOf:
                - $ref: '#/components/schemas/Decimal'
                - type: 'null'
              net:
                oneOf:
                - $ref: '#/components/schemas/Decimal'
                - type: 'null'
              paymentFrequency:
                oneOf:
                - $ref: '#/components/schemas/PaymentFrequency'
                - type: 'null'
              annual:
                description: Gross premium per year (gross × payments per year).
                readOnly: true
                oneOf:
                - $ref: '#/components/schemas/Decimal'
                - type: 'null'
          startDate:
            type:
            - string
            - 'null'
            format: date
          endDate:
            type:
            - string
            - 'null'
            format: date
          insuredSum:
            type:
            - string
            - 'null'
          notes:
            type:
            - string
            - 'null'
          typeSpecificData:
            $ref: '#/components/schemas/TypeSpecificData'
          status:
            $ref: '#/components/schemas/ContractStatus'
          statusLabel:
            type: string
            readOnly: true
            examples:
            - Aktiv
          coverage:
            oneOf:
            - $ref: '#/components/schemas/ContractCoverage'
            - type: 'null'
          allowedActions:
            type: array
            readOnly: true
            items:
              $ref: '#/components/schemas/ContractAllowedAction'
          source:
            $ref: '#/components/schemas/ContractSource'
          providerManaged:
            type: boolean
            readOnly: true
            description: Kept in sync by a connected provider (pool, comparison portal, F&B).
          externalReferences:
            type: array
            items:
              $ref: '#/components/schemas/ExternalReference'
      - $ref: '#/components/schemas/Timestamps'
    LabeledValue:
      type: object
      required:
      - value
      - label
      properties:
        value:
          type: string
        label:
          type: string
    ContractFieldDefinition:
      type: object
      required:
      - key
      - label
      - type
      - required
      properties:
        key:
          type: string
          examples:
          - tariffType
        label:
          type: string
          examples:
          - Tarifart
        type:
          type: string
          enum:
          - string
          - number
          - boolean
          - select
          - date
          - textarea
        required:
          type: boolean
        unit:
          type:
          - string
          - 'null'
          examples:
          - €
          - '%'
          - km
          - €/Monat
        default:
          type:
          - string
          - number
          - boolean
          - 'null'
        options:
          type: array
          description: Only for `select`.
          items:
            $ref: '#/components/schemas/LabeledValue'
        validation:
          type: object
          properties:
            maxLength:
              type: integer
            min:
              type: number
            max:
              type: number
            step:
              type: number
        showWhen:
          type:
          - object
          - 'null'
          description: The field only applies when another field has one of the given values.
          properties:
            field:
              type: string
              examples:
              - coverageType
            values:
              type: array
              items:
                type: string
              examples:
              - - partial
                - comprehensive
        group:
          type:
          - string
          - 'null'
          description: Section of long forms, e.g. `registration` for vehicles.
        extended:
          type: boolean
          description: Optional detail field, hidden in the short form.
        description:
          type:
          - string
          - 'null'
    ContractTypeDefinition:
      type: object
      required:
      - type
      - label
      - group
      - contactTypes
      - fields
      properties:
        type:
          $ref: '#/components/schemas/ContractType'
        label:
          type: string
          examples:
          - Haftpflichtversicherung
        group:
          $ref: '#/components/schemas/ContractTypeGroup'
        groupLabel:
          type: string
          examples:
          - Haftpflicht & Recht
        contactTypes:
          type: array
          items:
            $ref: '#/components/schemas/ContactType'
        subtypeField:
          type:
          - string
          - 'null'
          description: Field that acts as subtype in lists and reports.
          examples:
          - tariffType
        fields:
          type: array
          items:
            $ref: '#/components/schemas/ContractFieldDefinition'
    Insurer:
      type: object
      required:
      - id
      - name
      properties:
        id:
          $ref: '#/components/schemas/Uuid'
        name:
          type: string
          examples:
          - Allianz Versicherungs-AG
        slug:
          type: string
          examples:
          - allianz-versicherungs-ag
        logoUrl:
          type:
          - string
          - 'null'
          format: uri
    InsurerDetail:
      allOf:
      - $ref: '#/components/schemas/Insurer'
      - type: object
        properties:
          website:
            type:
            - string
            - 'null'
            format: uri
          phone:
            type:
            - string
            - 'null'
          emails:
            type: array
            items:
              type: object
              required:
              - category
              - email
              properties:
                category:
                  type: string
                  enum:
                  - support
                  - claims
                  - life
                  - health
                  - motor
                  - broker
                email:
                  type: string
                  format: email
          brokerNote:
            type:
            - string
            - 'null'
            description: Hints for brokers maintained by Advision360.
          companySettings:
            type: object
            description: The company's own data for this insurer.
            properties:
              brokerNumber:
                type:
                - string
                - 'null'
                examples:
                - '27087'
              note:
                type:
                - string
                - 'null'
    DocumentType:
      type: string
      enum:
      - id_card
      - passport
      - residence_permit
      - broker_agreement
      - broker_power_of_attorney
      - privacy_policy
      - electronic_communication_consent
      - risk_analysis
      - advice_documentation
      - advice_waiver
      - needs_assessment
      - insurance_policy
      - policy_amendment
      - policy_terms
      - premium_invoice
      - insurer_correspondence
      - payslip
      - tax_assessment
      - pension_information
      - bank_investment_documents
      - asset_statement
      - birth_certificate
      - marriage_certificate
      - divorce_documents
      - proof_of_children
      - claim_notification
      - claim_documents
      - expert_report
      - benefit_claim
      - benefit_decision
      - other
    DocumentTypeGroup:
      type: string
      enum:
      - identity
      - broker_agreements
      - advice
      - insurance_contracts
      - financial_situation
      - personal_documents
      - claims_benefits
      - other
    DocumentSource:
      type: string
      description: How the document got into Advision360.
      enum:
      - api
      - upload
      - email_attachment
      - generated_print
      - lead_upload
      - portal_upload
      - signature_download
      - legacy_import
      - fnb_download
      - nafi_download
      - mrmoney_download
      - bipro_download
      - pdf_box
    Document:
      allOf:
      - type: object
        required:
        - id
        - contactId
        - contractId
        - filename
        - mimeType
        - sizeBytes
        - type
        - source
        - visibleInPortal
        - externalReferences
        properties:
          id:
            $ref: '#/components/schemas/Uuid'
          contactId:
            $ref: '#/components/schemas/Uuid'
          contractId:
            type:
            - string
            - 'null'
            format: uuid
          filename:
            type: string
            examples:
            - Police_PHV_2026.pdf
          mimeType:
            type: string
            examples:
            - application/pdf
          sizeBytes:
            type: integer
          type:
            oneOf:
            - $ref: '#/components/schemas/DocumentType'
            - type: 'null'
          typeLabel:
            type:
            - string
            - 'null'
            readOnly: true
          source:
            $ref: '#/components/schemas/DocumentSource'
          visibleInPortal:
            type: boolean
            readOnly: true
            description: Whether the contact sees the document in the customer portal (depends on `source`).
          documentDate:
            type: string
            format: date
          uploadedBy:
            oneOf:
            - $ref: '#/components/schemas/UserRef'
            - type: 'null'
          signatureRequestId:
            type:
            - string
            - 'null'
            format: uuid
            description: Set when the document is the signed result of a signature request.
          externalReferences:
            type: array
            items:
              $ref: '#/components/schemas/ExternalReference'
      - $ref: '#/components/schemas/Timestamps'
    ContractExtractionStatus:
      type: string
      enum:
      - pending
      - parsing
      - extracting
      - done
      - failed
    ContractExtraction:
      type: object
      required:
      - id
      - documentId
      - status
      - createdAt
      properties:
        id:
          $ref: '#/components/schemas/Uuid'
        documentId:
          $ref: '#/components/schemas/Uuid'
        contractId:
          type:
          - string
          - 'null'
          format: uuid
        contractType:
          oneOf:
          - $ref: '#/components/schemas/ContractType'
          - type: 'null'
        status:
          $ref: '#/components/schemas/ContractExtractionStatus'
        autoApply:
          type: boolean
        fields:
          type: array
          description: Only when `status` is `done`.
          items:
            type: object
            required:
            - field
            - value
            - state
            properties:
              field:
                type: string
                examples:
                - premium.gross
              label:
                type: string
                examples:
                - Beitrag brutto
              value:
                type:
                - string
                - number
                - boolean
                - 'null'
              currentValue:
                type:
                - string
                - number
                - boolean
                - 'null'
                description: Value on the target contract.
              state:
                type: string
                enum:
                - new
                - match
                - conflict
                - missing
        error:
          type:
          - string
          - 'null'
        appliedAt:
          type:
          - string
          - 'null'
          format: date-time
        createdAt:
          type: string
          format: date-time
    CorrespondenceTransactionType:
      type: string
      enum:
      - address-change
      - bank-details-change
      - name-change
      - contract-change
      - payment-frequency-change
      - document-request
      - cancellation
      - general-inquiry
      - claim-report
      - claim-status
      - risk-increase
      - relocation
      - premium-increase
      - premium-decrease
      - premium-suspension
      - dynamic-objection
      - beneficiary-change
      - status-report
      - contract-value
      - additional-payment
      - payout
    CorrespondenceStatus:
      type: string
      enum:
      - draft
      - sent
      - completed
      - follow_up
    CorrespondenceTransactionDefinition:
      type: object
      required:
      - type
      - label
      - group
      - fields
      properties:
        type:
          $ref: '#/components/schemas/CorrespondenceTransactionType'
        label:
          type: string
          examples:
          - Adressänderung
        group:
          type: string
          enum:
          - contract
          - premium
          - claims
          - documents
          - other
        contractTypes:
          type: array
          description: Empty means all contract types.
          items:
            $ref: '#/components/schemas/ContractType'
        fields:
          type: array
          items:
            type: object
            required:
            - key
            - label
            - type
            - required
            properties:
              key:
                type: string
                examples:
                - effectiveDate
              label:
                type: string
                examples:
                - Gültig ab
              type:
                type: string
                enum:
                - text
                - textarea
                - date
                - select
                - checkbox
                - number
                - currency
              required:
                type: boolean
              options:
                type: array
                items:
                  $ref: '#/components/schemas/LabeledValue'
    CorrespondenceCase:
      allOf:
      - type: object
        required:
        - id
        - contactId
        - contractIds
        - transactionType
        - status
        properties:
          id:
            $ref: '#/components/schemas/Uuid'
          contactId:
            $ref: '#/components/schemas/Uuid'
          contractIds:
            type: array
            items:
              $ref: '#/components/schemas/Uuid'
          insurerName:
            type:
            - string
            - 'null'
          transactionType:
            $ref: '#/components/schemas/CorrespondenceTransactionType'
          transactionLabel:
            type: string
            readOnly: true
          status:
            $ref: '#/components/schemas/CorrespondenceStatus'
          recipientEmail:
            type:
            - string
            - 'null'
            format: email
          subject:
            type:
            - string
            - 'null'
          body:
            type:
            - string
            - 'null'
          formData:
            type: object
            additionalProperties:
              type:
              - string
              - number
              - boolean
              - 'null'
          sentAt:
            type:
            - string
            - 'null'
            format: date-time
          createdBy:
            oneOf:
            - $ref: '#/components/schemas/UserRef'
            - type: 'null'
      - $ref: '#/components/schemas/Timestamps'
    SignatureRequestStatus:
      type: string
      enum:
      - started
      - partially_signed
      - completed
      - declined
      - expired
      - cancelled
      - error
    SignerStatus:
      type: string
      enum:
      - pending
      - invited
      - viewed
      - signed
      - declined
    SignatureDeliveryMode:
      type: string
      description: '`email` sends an invitation link, `portal` shows the request in the customer portal, `local` returns an
        `accessUrl` for signing on the advisor''s device.'
      enum:
      - email
      - portal
      - local
    SignatureRequestCreate:
      type: object
      required:
      - contactId
      - documents
      - signers
      properties:
        contactId:
          $ref: '#/components/schemas/Uuid'
        title:
          type: string
          maxLength: 255
          examples:
          - Maklervollmacht und Datenschutz
        message:
          type: string
          maxLength: 2000
          description: Text of the invitation email.
        signingOrder:
          type: string
          enum:
          - parallel
          - sequential
          default: parallel
        expiresAt:
          type: string
          format: date-time
        requireEmailOtp:
          type: boolean
          default: false
          description: 'ADV Sign: signers confirm a one-time code sent by email.'
        documents:
          type: array
          minItems: 1
          maxItems: 20
          items:
            type: object
            description: Exactly one of the two IDs.
            properties:
              documentId:
                $ref: '#/components/schemas/Uuid'
              standardDocumentId:
                $ref: '#/components/schemas/Uuid'
        signers:
          type: array
          minItems: 1
          maxItems: 6
          description: inSign supports one signer.
          items:
            type: object
            required:
            - role
            - name
            properties:
              role:
                type: string
                enum:
                - customer
                - co_signer
                - advisor
              name:
                type: string
                maxLength: 255
              email:
                type: string
                format: email
                description: Required for `email` delivery.
              deliveryMode:
                $ref: '#/components/schemas/SignatureDeliveryMode'
        fields:
          type: array
          maxItems: 200
          items:
            type: object
            required:
            - documentIndex
            - signerIndex
            - type
            - page
            - x
            - 'y'
            - width
            - height
            properties:
              documentIndex:
                type: integer
                minimum: 0
              signerIndex:
                type: integer
                minimum: 0
              type:
                type: string
                enum:
                - signature
                - initials
                - text
                - date
                - checkbox
              page:
                type: integer
                minimum: 1
              x:
                type: number
                minimum: 0
                maximum: 1
              'y':
                type: number
                minimum: 0
                maximum: 1
              width:
                type: number
                minimum: 0
                maximum: 1
              height:
                type: number
                minimum: 0
                maximum: 1
              required:
                type: boolean
                default: true
              label:
                type: string
    SignatureRequest:
      allOf:
      - type: object
        required:
        - id
        - contactId
        - provider
        - status
        - documents
        - signers
        properties:
          id:
            $ref: '#/components/schemas/Uuid'
          contactId:
            $ref: '#/components/schemas/Uuid'
          provider:
            type: string
            enum:
            - adv_sign
            - insign
          title:
            type:
            - string
            - 'null'
          status:
            $ref: '#/components/schemas/SignatureRequestStatus'
          signingOrder:
            type: string
            enum:
            - parallel
            - sequential
          accessUrl:
            type:
            - string
            - 'null'
            format: uri
            description: 'Only for `local` delivery: open on the advisor''s device to sign in person.'
          documents:
            type: array
            items:
              type: object
              required:
              - name
              properties:
                name:
                  type: string
                sourceDocumentId:
                  type:
                  - string
                  - 'null'
                  format: uuid
                standardDocumentId:
                  type:
                  - string
                  - 'null'
                  format: uuid
                signedDocumentId:
                  type:
                  - string
                  - 'null'
                  format: uuid
                  description: Download via `GET /documents/{documentId}/content` once completed.
          signers:
            type: array
            items:
              type: object
              required:
              - role
              - name
              - status
              properties:
                role:
                  type: string
                  enum:
                  - customer
                  - co_signer
                  - advisor
                name:
                  type: string
                email:
                  type:
                  - string
                  - 'null'
                  format: email
                deliveryMode:
                  $ref: '#/components/schemas/SignatureDeliveryMode'
                status:
                  $ref: '#/components/schemas/SignerStatus'
                signedAt:
                  type:
                  - string
                  - 'null'
                  format: date-time
                declineReason:
                  type:
                  - string
                  - 'null'
          completedAt:
            type:
            - string
            - 'null'
            format: date-time
          errorCode:
            type:
            - string
            - 'null'
          createdBy:
            oneOf:
            - $ref: '#/components/schemas/UserRef'
            - type: 'null'
      - $ref: '#/components/schemas/Timestamps'
    LeadSource:
      type: string
      enum:
      - website
      - referral
      - phone
      - event
      - social_media
      - advertisement
      - partner
      - landing_page
      - registration
      - api
      - other
    LeadStage:
      type: object
      required:
      - id
      - slug
      - name
      - position
      - isSystem
      - isFinal
      properties:
        id:
          $ref: '#/components/schemas/Uuid'
        slug:
          type: string
          examples:
          - new
        name:
          type: string
          examples:
          - Neu
        color:
          $ref: '#/components/schemas/LabelColor'
        position:
          type: integer
        isSystem:
          type: boolean
        isFinal:
          type: boolean
    LeadInput:
      type: object
      properties:
        firstName:
          type: string
          maxLength: 100
        lastName:
          type: string
          maxLength: 100
        email:
          type:
          - string
          - 'null'
          format: email
          maxLength: 255
        phone:
          type:
          - string
          - 'null'
          maxLength: 50
        source:
          $ref: '#/components/schemas/LeadSource'
        sourceUrl:
          type:
          - string
          - 'null'
          format: uri
        notes:
          type:
          - string
          - 'null'
        additionalFields:
          type: object
          description: Free key-value data from your form (interests, desired product, ...).
          additionalProperties:
            type:
            - string
            - number
            - boolean
            - 'null'
        externalReferences:
          type: array
          items:
            $ref: '#/components/schemas/ExternalReference'
    LeadIntake:
      type: object
      required:
      - firstName
      - lastName
      properties:
        firstName:
          type: string
          maxLength: 100
        lastName:
          type: string
          maxLength: 100
        email:
          type: string
          format: email
          maxLength: 255
        phone:
          type: string
          maxLength: 50
        source:
          $ref: '#/components/schemas/LeadSource'
        notes:
          type: string
        additionalFields:
          type: object
          additionalProperties:
            type:
            - string
            - number
            - boolean
        _meta:
          type: object
          properties:
            url:
              type: string
              format: uri
              description: Page the form was submitted on.
        _key:
          type: string
          description: Publishable key, alternative to the `X-API-Key` header.
        _redirect:
          type: string
          format: uri
        _test:
          type: boolean
          description: Marks the lead as test lead.
    Lead:
      allOf:
      - type: object
        required:
        - id
        - firstName
        - lastName
        - stage
        - isTest
        - externalReferences
        properties:
          id:
            $ref: '#/components/schemas/Uuid'
          firstName:
            type: string
          lastName:
            type: string
          email:
            type:
            - string
            - 'null'
            format: email
          phone:
            type:
            - string
            - 'null'
            description: E.164 when it could be normalized.
          source:
            oneOf:
            - $ref: '#/components/schemas/LeadSource'
            - type: 'null'
          sourceUrl:
            type:
            - string
            - 'null'
            format: uri
          notes:
            type:
            - string
            - 'null'
          additionalFields:
            type: object
            additionalProperties: true
          stage:
            $ref: '#/components/schemas/LeadStage'
          owner:
            oneOf:
            - $ref: '#/components/schemas/UserRef'
            - type: 'null'
          isTest:
            type: boolean
          isSpamSuspect:
            type: boolean
            readOnly: true
          attachments:
            type: array
            items:
              type: object
              required:
              - id
              - filename
              - mimeType
              - sizeBytes
              properties:
                id:
                  $ref: '#/components/schemas/Uuid'
                filename:
                  type: string
                mimeType:
                  type: string
                sizeBytes:
                  type: integer
          convertedContactId:
            type:
            - string
            - 'null'
            format: uuid
          convertedAt:
            type:
            - string
            - 'null'
            format: date-time
          externalReferences:
            type: array
            items:
              $ref: '#/components/schemas/ExternalReference'
      - $ref: '#/components/schemas/Timestamps'
    TaskStatus:
      type: string
      enum:
      - backlog
      - open
      - in_progress
      - done
      - canceled
    TaskPriority:
      type: string
      enum:
      - high
      - medium
      - low
    TaskInput:
      type: object
      properties:
        title:
          type: string
          maxLength: 255
        description:
          type:
          - string
          - 'null'
        status:
          $ref: '#/components/schemas/TaskStatus'
        priority:
          $ref: '#/components/schemas/TaskPriority'
        assigneeId:
          type:
          - string
          - 'null'
          format: uuid
        contactId:
          type:
          - string
          - 'null'
          format: uuid
        leadId:
          type:
          - string
          - 'null'
          format: uuid
        dueAt:
          type:
          - string
          - 'null'
          format: date-time
        dueAllDay:
          type: boolean
          description: Only the date of `dueAt` matters.
        estimatedMinutes:
          type:
          - integer
          - 'null'
          minimum: 0
        isPrivate:
          type: boolean
          description: Only visible to assignee and creator.
        checklist:
          type: array
          maxItems: 200
          items:
            type: object
            required:
            - text
            - done
            properties:
              text:
                type: string
                maxLength: 500
              done:
                type: boolean
        tags:
          type: array
          items:
            type: string
        externalReferences:
          type: array
          items:
            $ref: '#/components/schemas/ExternalReference'
    Task:
      allOf:
      - type: object
        required:
        - id
        - title
        - status
        - priority
        properties:
          id:
            $ref: '#/components/schemas/Uuid'
          assignee:
            oneOf:
            - $ref: '#/components/schemas/UserRef'
            - type: 'null'
          createdBy:
            oneOf:
            - $ref: '#/components/schemas/UserRef'
            - type: 'null'
          completedBy:
            oneOf:
            - $ref: '#/components/schemas/UserRef'
            - type: 'null'
          completedAt:
            type:
            - string
            - 'null'
            format: date-time
          parentTaskId:
            type:
            - string
            - 'null'
            format: uuid
      - $ref: '#/components/schemas/TaskInput'
      - $ref: '#/components/schemas/Timestamps'
    TaskComment:
      type: object
      required:
      - id
      - content
      - author
      - createdAt
      properties:
        id:
          $ref: '#/components/schemas/Uuid'
        parentCommentId:
          type:
          - string
          - 'null'
          format: uuid
        content:
          type: string
        author:
          oneOf:
          - $ref: '#/components/schemas/UserRef'
          - type: 'null'
        editedAt:
          type:
          - string
          - 'null'
          format: date-time
        createdAt:
          type: string
          format: date-time
    AppointmentType:
      type: string
      enum:
      - appointment
      - consultation
      - call
      - internal
      - absence
      - other
    AppointmentInput:
      type: object
      properties:
        type:
          $ref: '#/components/schemas/AppointmentType'
        title:
          type: string
          maxLength: 255
        description:
          type:
          - string
          - 'null'
          maxLength: 5000
        location:
          type:
          - string
          - 'null'
          maxLength: 255
        allDay:
          type: boolean
          default: false
        startAt:
          type: string
          format: date-time
          description: For all-day appointments only the date counts.
        endAt:
          type: string
          format: date-time
        recurrence:
          type:
          - object
          - 'null'
          properties:
            rrule:
              type: string
              maxLength: 500
              description: 'RFC 5545 RRULE. Supported: FREQ (DAILY, WEEKLY, MONTHLY, YEARLY), INTERVAL ≤ 99, COUNT ≤ 500,
                UNTIL, BYDAY, BYMONTHDAY, BYMONTH, BYSETPOS, WKST.'
              examples:
              - FREQ=WEEKLY;BYDAY=MO;COUNT=10
        ownerId:
          type: string
          format: uuid
          description: Defaults to the acting user.
        participantIds:
          type: array
          maxItems: 50
          description: Internal team members.
          items:
            $ref: '#/components/schemas/Uuid'
        contactId:
          type:
          - string
          - 'null'
          format: uuid
        leadId:
          type:
          - string
          - 'null'
          format: uuid
        reminderMinutes:
          type:
          - integer
          - 'null'
          enum:
          - 5
          - 15
          - 30
          - 60
          - 1440
          - null
        externalReferences:
          type: array
          items:
            $ref: '#/components/schemas/ExternalReference'
    Appointment:
      allOf:
      - type: object
        required:
        - id
        - type
        - title
        - startAt
        - endAt
        - allDay
        - owner
        properties:
          id:
            $ref: '#/components/schemas/Uuid'
          seriesId:
            type:
            - string
            - 'null'
            format: uuid
            description: Master appointment of a recurring series.
          occurrenceStart:
            type:
            - string
            - 'null'
            format: date-time
            description: Original start of this occurrence.
          owner:
            $ref: '#/components/schemas/UserRef'
          participants:
            type: array
            items:
              $ref: '#/components/schemas/UserRef'
      - $ref: '#/components/schemas/AppointmentInput'
      - $ref: '#/components/schemas/Timestamps'
    OfferProcessStatus:
      type: string
      enum:
      - started
      - results_received
      - offer_received
      - application_saved
      - application_received
      - completed
      - expired
      - error
    OfferProcess:
      allOf:
      - type: object
        required:
        - id
        - contactId
        - provider
        - line
        - status
        properties:
          id:
            $ref: '#/components/schemas/Uuid'
          contactId:
            $ref: '#/components/schemas/Uuid'
          provider:
            type: string
            enum:
            - fnb
            - mrmoney
            - nafi
            - bipro_stuttgarter
          line:
            type: string
            description: Product line, e.g. `kfz`, `household`, `personalLiability`, `occupationalDisability`.
          productLabel:
            type:
            - string
            - 'null'
          status:
            $ref: '#/components/schemas/OfferProcessStatus'
          insurerName:
            type:
            - string
            - 'null'
          premium:
            oneOf:
            - $ref: '#/components/schemas/Decimal'
            - type: 'null'
          paymentFrequency:
            oneOf:
            - $ref: '#/components/schemas/PaymentFrequency'
            - type: 'null'
          contractId:
            type:
            - string
            - 'null'
            format: uuid
            description: Contract created from the offer.
          documentIds:
            type: array
            items:
              $ref: '#/components/schemas/Uuid'
      - $ref: '#/components/schemas/Timestamps'
    IntegrationCategory:
      type: string
      enum:
      - ams
      - broker_pool
      - comparison_platform
      - insurer
      - document_service
    IntegrationProvider:
      type: object
      required:
      - key
      - name
      - category
      - standards
      - capabilities
      properties:
        key:
          type: string
          examples:
          - professional_works
        name:
          type: string
          examples:
          - Professional Works
        category:
          $ref: '#/components/schemas/IntegrationCategory'
        description:
          type:
          - string
          - 'null'
        standards:
          type: array
          items:
            type: string
            enum:
            - rest
            - bipro_420
            - bipro_430
            - gdv_vu_vermittler
            - csv
            - oauth2
        capabilities:
          type: array
          items:
            type: string
            enum:
            - contacts_inbound
            - contacts_outbound
            - contracts_inbound
            - contracts_outbound
            - documents_inbound
            - documents_outbound
            - offers
            - applications
            - deeplinks
        requiredFeature:
          $ref: '#/components/schemas/LicenseFeature'
        logoUrl:
          type:
          - string
          - 'null'
          format: uri
    IntegrationConnectionStatus:
      type: string
      enum:
      - connected
      - pending_authorization
      - disabled
      - error
    SyncScope:
      type: string
      enum:
      - contacts
      - contracts
      - documents
    IntegrationSettings:
      type: object
      properties:
        direction:
          type: string
          enum:
          - inbound
          - outbound
          - bidirectional
          default: inbound
        conflictPolicy:
          type: string
          enum:
          - source_wins
          - advision_wins
          - newest_wins
          default: source_wins
          description: Which side wins when a field changed on both sides since the last sync.
        scopes:
          type: array
          items:
            $ref: '#/components/schemas/SyncScope'
        schedule:
          type: string
          enum:
          - manual
          - hourly
          - nightly
          default: nightly
        deleteMissing:
          type: boolean
          default: false
          description: Remove records that no longer exist in the source after a full sync.
    IntegrationConnection:
      allOf:
      - type: object
        required:
        - id
        - provider
        - providerName
        - status
        - enabled
        - isPrimary
        - settings
        properties:
          id:
            $ref: '#/components/schemas/Uuid'
          provider:
            type: string
            examples:
            - codie_finakom
          providerName:
            type: string
            examples:
            - CODie (via Finakom-Middleware)
          status:
            $ref: '#/components/schemas/IntegrationConnectionStatus'
          enabled:
            type: boolean
          isPrimary:
            type: boolean
          owner:
            oneOf:
            - $ref: '#/components/schemas/UserRef'
            - type: 'null'
          environment:
            type: string
            enum:
            - production
            - test
          settings:
            $ref: '#/components/schemas/IntegrationSettings'
          lastSyncRun:
            oneOf:
            - $ref: '#/components/schemas/SyncRun'
            - type: 'null'
          importedCounts:
            type: object
            properties:
              contacts:
                type: integer
              contracts:
                type: integer
              documents:
                type: integer
      - $ref: '#/components/schemas/Timestamps'
    SyncRunStatus:
      type: string
      enum:
      - queued
      - running
      - completed
      - completed_with_issues
      - failed
      - cancelled
    SyncCounter:
      type: object
      properties:
        created:
          type: integer
        updated:
          type: integer
        unchanged:
          type: integer
        deleted:
          type: integer
        failed:
          type: integer
    SyncRun:
      type: object
      required:
      - id
      - connectionId
      - provider
      - status
      - mode
      - startedAt
      properties:
        id:
          $ref: '#/components/schemas/Uuid'
        connectionId:
          $ref: '#/components/schemas/Uuid'
        provider:
          type: string
        status:
          $ref: '#/components/schemas/SyncRunStatus'
        mode:
          type: string
          enum:
          - incremental
          - full
        trigger:
          type: string
          enum:
          - manual
          - schedule
          - api
        step:
          type:
          - string
          - 'null'
          examples:
          - contracts
        progress:
          type:
          - number
          - 'null'
          minimum: 0
          maximum: 1
        counters:
          type: object
          properties:
            contacts:
              $ref: '#/components/schemas/SyncCounter'
            contracts:
              $ref: '#/components/schemas/SyncCounter'
            documents:
              $ref: '#/components/schemas/SyncCounter'
        error:
          type:
          - string
          - 'null'
        startedAt:
          type: string
          format: date-time
        finishedAt:
          type:
          - string
          - 'null'
          format: date-time
    SyncIssue:
      type: object
      required:
      - id
      - severity
      - code
      - message
      properties:
        id:
          $ref: '#/components/schemas/Uuid'
        severity:
          type: string
          enum:
          - warning
          - error
        code:
          type: string
          examples:
          - unknown_contract_type
          - invalid_iban
          - duplicate_policy_number
        message:
          type: string
        objectType:
          $ref: '#/components/schemas/SyncObjectType'
        externalId:
          type:
          - string
          - 'null'
        objectId:
          type:
          - string
          - 'null'
          format: uuid
    FieldMapping:
      type: object
      required:
      - objectType
      - sourceField
      - targetField
      properties:
        objectType:
          type: string
          enum:
          - contact
          - contract
        sourceField:
          type: string
          examples:
          - VN_Beruf
        targetField:
          type: string
          description: Contact field key (e.g. `profession.profession`), contract field (e.g. `premium.gross`) or `customFields.<key>`.
          examples:
          - profession.profession
        transform:
          type: string
          enum:
          - none
          - trim
          - uppercase
          - lowercase
          - date
          - decimal
          - value_map
          default: none
        dateFormat:
          type:
          - string
          - 'null'
          examples:
          - dd.MM.yyyy
        valueMap:
          type: object
          additionalProperties:
            type: string
          examples:
          - '1': mr
            '2': mrs
    PortfolioFormat:
      type: string
      enum:
      - gdv_vu_vermittler
      - bipro_430_4
      - csv
    PortfolioTransferStatus:
      type: string
      enum:
      - uploaded
      - validating
      - validated
      - importing
      - completed
      - completed_with_issues
      - failed
      - discarded
    PortfolioTransfer:
      type: object
      required:
      - id
      - format
      - status
      - createdAt
      properties:
        id:
          $ref: '#/components/schemas/Uuid'
        format:
          $ref: '#/components/schemas/PortfolioFormat'
        filename:
          type: string
          examples:
          - VUVM_20261001.gdv
        source:
          type:
          - string
          - 'null'
        status:
          $ref: '#/components/schemas/PortfolioTransferStatus'
        insurer:
          oneOf:
          - $ref: '#/components/schemas/Insurer'
          - type: 'null'
        summary:
          type: object
          properties:
            records:
              type: object
              description: Number of records per GDV record type.
              additionalProperties:
                type: integer
              examples:
              - '0100': 1240
                '0200': 3315
                '0210': 3301
                '9999': 1
            contacts:
              $ref: '#/components/schemas/SyncCounter'
            contracts:
              $ref: '#/components/schemas/SyncCounter'
            warnings:
              type: integer
            errors:
              type: integer
        createdBy:
          oneOf:
          - $ref: '#/components/schemas/UserRef'
          - type: 'null'
        createdAt:
          type: string
          format: date-time
        completedAt:
          type:
          - string
          - 'null'
          format: date-time
    GdvLineMapping:
      type: object
      required:
      - gdvLine
      - contractType
      properties:
        gdvLine:
          type: string
          pattern: ^\d{3}$
          description: GDV Sparte, e.g. 010 Leben, 020 Kranken, 030 Unfall, 040 Haftpflicht, 050 Kraftfahrt, 070 Rechtsschutz,
            130 Hausrat, 140 Wohngebäude.
          examples:
          - '040'
        gdvLineLabel:
          type: string
          readOnly: true
          examples:
          - Haftpflicht
        productCode:
          type:
          - string
          - 'null'
          description: Optional insurer product code for a finer mapping.
        contractType:
          $ref: '#/components/schemas/ContractType'
        isOverride:
          type: boolean
          readOnly: true
    ExportJob:
      type: object
      required:
      - id
      - format
      - status
      - createdAt
      properties:
        id:
          $ref: '#/components/schemas/Uuid'
        format:
          type: string
        objects:
          type: array
          items:
            type: string
        status:
          type: string
          enum:
          - queued
          - running
          - completed
          - failed
        recordCount:
          type:
          - integer
          - 'null'
        downloadUrl:
          type:
          - string
          - 'null'
          format: uri
        expiresAt:
          type:
          - string
          - 'null'
          format: date-time
        createdAt:
          type: string
          format: date-time
    BiproCategory:
      type: string
      enum:
      - contract_documents
      - portfolio_changes
      - collections
      - claims
      - commissions
      - general_correspondence
    BiproDeliveryStatus:
      type: string
      enum:
      - received
      - matched
      - unmatched
      - processed
      - acknowledged
      - failed
    BiproDelivery:
      type: object
      required:
      - id
      - insurer
      - category
      - status
      - receivedAt
      properties:
        id:
          $ref: '#/components/schemas/Uuid'
        insurer:
          $ref: '#/components/schemas/Insurer'
        norm:
          type: string
          examples:
          - '430.1'
        category:
          $ref: '#/components/schemas/BiproCategory'
        categoryLabel:
          type: string
          examples:
          - Vertragsdokumente
        transferId:
          type: string
          description: BiPRO delivery ID of the insurer.
        status:
          $ref: '#/components/schemas/BiproDeliveryStatus'
        policyNumber:
          type:
          - string
          - 'null'
        contactId:
          type:
          - string
          - 'null'
          format: uuid
        contractId:
          type:
          - string
          - 'null'
          format: uuid
        documentIds:
          type: array
          items:
            $ref: '#/components/schemas/Uuid'
        dataRecords:
          type: array
          description: Structured content, e.g. changed premium or new address.
          items:
            type: object
            properties:
              type:
                type: string
                examples:
                - premium_change
              values:
                type: object
                additionalProperties: true
        receivedAt:
          type: string
          format: date-time
        acknowledgedAt:
          type:
          - string
          - 'null'
          format: date-time
    SyncObjectType:
      type: string
      enum:
      - contact
      - contract
      - lead
      - document
      - task
      - appointment
      - claim
      - commission_entry
      - note
    ExternalReferenceMapping:
      type: object
      required:
      - objectType
      - id
      - source
      - externalId
      properties:
        objectType:
          $ref: '#/components/schemas/SyncObjectType'
        id:
          $ref: '#/components/schemas/Uuid'
        source:
          type: string
        externalId:
          type: string
        linkedAt:
          type: string
          format: date-time
    SyncCheckpoint:
      type: object
      properties:
        eventCursor:
          type:
          - string
          - 'null'
        updatedSince:
          type:
          - string
          - 'null'
          format: date-time
        state:
          type: object
          description: Free connector state, max. 16 KB.
          additionalProperties: true
        updatedAt:
          type: string
          format: date-time
          readOnly: true
    ClaimType:
      type: string
      enum:
      - property
      - liability
      - motor
      - health
      - accident
      - legal
      - life
      - disability
      - business
      - other
    ClaimStatus:
      type: string
      description: '`reported` = sent to the insurer, `settled` = paid out, `closed` = finished without further action.'
      enum:
      - draft
      - reported
      - in_review
      - expert_assessment
      - settled
      - partially_settled
      - rejected
      - closed
      - reopened
    ClaimInput:
      type: object
      properties:
        contractId:
          $ref: '#/components/schemas/Uuid'
        type:
          $ref: '#/components/schemas/ClaimType'
        dateOfLoss:
          type: string
          format: date
        timeOfLoss:
          type:
          - string
          - 'null'
          pattern: ^\d{2}:\d{2}$
          examples:
          - '14:30'
        description:
          type: string
          maxLength: 10000
        location:
          $ref: '#/components/schemas/Address'
        estimatedAmount:
          oneOf:
          - $ref: '#/components/schemas/Decimal'
          - type: 'null'
        deductible:
          oneOf:
          - $ref: '#/components/schemas/Decimal'
          - type: 'null'
        insurerClaimNumber:
          type:
          - string
          - 'null'
          maxLength: 100
        insurerHandler:
          type:
          - object
          - 'null'
          properties:
            name:
              type: string
            email:
              type: string
              format: email
            phone:
              type: string
        policeReportNumber:
          type:
          - string
          - 'null'
        thirdParties:
          type: array
          items:
            type: object
            properties:
              name:
                type: string
              role:
                type: string
                enum:
                - injured_party
                - witness
                - other_party
                - expert
              contact:
                type: string
        documentIds:
          type: array
          items:
            $ref: '#/components/schemas/Uuid'
        externalReferences:
          type: array
          items:
            $ref: '#/components/schemas/ExternalReference'
    Claim:
      allOf:
      - type: object
        required:
        - id
        - contactId
        - contractId
        - type
        - status
        - dateOfLoss
        - internalNumber
        properties:
          id:
            $ref: '#/components/schemas/Uuid'
          internalNumber:
            type: string
            readOnly: true
            examples:
            - S-2026-0042
          contactId:
            $ref: '#/components/schemas/Uuid'
          status:
            $ref: '#/components/schemas/ClaimStatus'
          statusLabel:
            type: string
            readOnly: true
            examples:
            - In Prüfung
          settledAmount:
            oneOf:
            - $ref: '#/components/schemas/Decimal'
            - type: 'null'
          reportedAt:
            type:
            - string
            - 'null'
            format: date-time
          settledAt:
            type:
            - string
            - 'null'
            format: date-time
          correspondenceCaseIds:
            type: array
            items:
              $ref: '#/components/schemas/Uuid'
          owner:
            oneOf:
            - $ref: '#/components/schemas/UserRef'
            - type: 'null'
      - $ref: '#/components/schemas/ClaimInput'
      - $ref: '#/components/schemas/Timestamps'
    CommissionType:
      type: string
      description: '`acquisition` Abschlussprovision, `portfolio` Bestandsprovision, `dynamics` Dynamikprovision, `cancellation_reserve`
        Stornoreserve, `chargeback` Rückbelastung.'
      enum:
      - acquisition
      - portfolio
      - dynamics
      - bonus
      - cancellation_reserve
      - cancellation_reserve_release
      - chargeback
      - other
    CommissionStatement:
      type: object
      required:
      - id
      - insurerName
      - periodFrom
      - periodTo
      - status
      - totalAmount
      properties:
        id:
          $ref: '#/components/schemas/Uuid'
        insurerId:
          type:
          - string
          - 'null'
          format: uuid
        insurerName:
          type: string
        statementNumber:
          type:
          - string
          - 'null'
        periodFrom:
          type: string
          format: date
        periodTo:
          type: string
          format: date
        source:
          type: string
          enum:
          - bipro
          - gdv
          - upload
          - manual
        status:
          type: string
          enum:
          - processing
          - received
          - reconciled
          - disputed
        totalAmount:
          $ref: '#/components/schemas/Decimal'
        entryCount:
          type: integer
        unmatchedCount:
          type: integer
        documentId:
          type:
          - string
          - 'null'
          format: uuid
        receivedAt:
          type: string
          format: date-time
    CommissionEntry:
      type: object
      required:
      - id
      - statementId
      - type
      - amount
      - bookedOn
      properties:
        id:
          $ref: '#/components/schemas/Uuid'
        statementId:
          $ref: '#/components/schemas/Uuid'
        contractId:
          type:
          - string
          - 'null'
          format: uuid
        contactId:
          type:
          - string
          - 'null'
          format: uuid
        policyNumber:
          type:
          - string
          - 'null'
        insuredName:
          type:
          - string
          - 'null'
        type:
          $ref: '#/components/schemas/CommissionType'
        amount:
          $ref: '#/components/schemas/Decimal'
        rate:
          type:
          - number
          - 'null'
          description: Commission rate in per mille of the assessment base.
        assessmentBase:
          oneOf:
          - $ref: '#/components/schemas/Decimal'
          - type: 'null'
        bookedOn:
          type: string
          format: date
        liabilityEndsOn:
          type:
          - string
          - 'null'
          format: date
          description: End of the cancellation liability period (Stornohaftungszeit).
        note:
          type:
          - string
          - 'null'
    EmailAddress:
      type: object
      required:
      - email
      properties:
        email:
          type: string
          format: email
        name:
          type:
          - string
          - 'null'
    EmailThread:
      type: object
      required:
      - id
      - subject
      - messageCount
      - lastMessageAt
      properties:
        id:
          $ref: '#/components/schemas/Uuid'
        mailboxId:
          $ref: '#/components/schemas/Uuid'
        subject:
          type: string
        snippet:
          type:
          - string
          - 'null'
        contactId:
          type:
          - string
          - 'null'
          format: uuid
        leadId:
          type:
          - string
          - 'null'
          format: uuid
        participants:
          type: array
          items:
            $ref: '#/components/schemas/EmailAddress'
        messageCount:
          type: integer
        unread:
          type: boolean
        lastMessageAt:
          type: string
          format: date-time
    Email:
      type: object
      required:
      - id
      - threadId
      - direction
      - status
      - from
      - to
      - subject
      - createdAt
      properties:
        id:
          $ref: '#/components/schemas/Uuid'
        threadId:
          $ref: '#/components/schemas/Uuid'
        mailboxId:
          $ref: '#/components/schemas/Uuid'
        direction:
          type: string
          enum:
          - in
          - out
        status:
          type: string
          enum:
          - pending
          - sent
          - failed
          - received
        origin:
          type: string
          enum:
          - user
          - automation
          - api
          - marketing
        from:
          $ref: '#/components/schemas/EmailAddress'
        to:
          type: array
          items:
            $ref: '#/components/schemas/EmailAddress'
        cc:
          type: array
          items:
            $ref: '#/components/schemas/EmailAddress'
        bcc:
          type: array
          items:
            $ref: '#/components/schemas/EmailAddress'
        subject:
          type: string
        snippet:
          type:
          - string
          - 'null'
        text:
          type:
          - string
          - 'null'
        html:
          type:
          - string
          - 'null'
        contactId:
          type:
          - string
          - 'null'
          format: uuid
        leadId:
          type:
          - string
          - 'null'
          format: uuid
        attachments:
          type: array
          items:
            type: object
            required:
            - id
            - filename
            - mimeType
            - sizeBytes
            properties:
              id:
                $ref: '#/components/schemas/Uuid'
              filename:
                type: string
              mimeType:
                type: string
              sizeBytes:
                type: integer
              documentId:
                type:
                - string
                - 'null'
                format: uuid
                description: Set when the attachment was filed as a contact document.
        messageId:
          type:
          - string
          - 'null'
          description: RFC 5322 Message-ID.
        tracking:
          type: object
          properties:
            deliveredAt:
              type:
              - string
              - 'null'
              format: date-time
            openedAt:
              type:
              - string
              - 'null'
              format: date-time
            clickedAt:
              type:
              - string
              - 'null'
              format: date-time
            failedAt:
              type:
              - string
              - 'null'
              format: date-time
        sentAt:
          type:
          - string
          - 'null'
          format: date-time
        createdAt:
          type: string
          format: date-time
    EmailSend:
      type: object
      required:
      - mailboxId
      - to
      - subject
      properties:
        mailboxId:
          $ref: '#/components/schemas/Uuid'
        to:
          type: array
          minItems: 1
          maxItems: 50
          items:
            $ref: '#/components/schemas/EmailAddress'
        cc:
          type: array
          items:
            $ref: '#/components/schemas/EmailAddress'
        bcc:
          type: array
          items:
            $ref: '#/components/schemas/EmailAddress'
        subject:
          type: string
          maxLength: 998
        html:
          type: string
          description: HTML body. Sent 1:1; a plain-text part is generated.
        text:
          type: string
          description: Plain-text body, used when `html` is missing.
        templateId:
          $ref: '#/components/schemas/Uuid'
        contactId:
          $ref: '#/components/schemas/Uuid'
        leadId:
          $ref: '#/components/schemas/Uuid'
        replyToEmailId:
          $ref: '#/components/schemas/Uuid'
        attachmentDocumentIds:
          type: array
          maxItems: 10
          items:
            $ref: '#/components/schemas/Uuid'
        sendAt:
          type: string
          format: date-time
          description: Schedule the email instead of sending it now.
    Segment:
      type: object
      required:
      - id
      - name
      - contactCount
      properties:
        id:
          $ref: '#/components/schemas/Uuid'
        name:
          type: string
          examples:
          - Privatkunden ohne Haftpflicht
        description:
          type:
          - string
          - 'null'
        contactCount:
          type: integer
        criteria:
          type: object
          description: Filter definition, same parameters as `GET /contacts`.
          additionalProperties: true
        updatedAt:
          type: string
          format: date-time
    FunnelStatus:
      type: string
      enum:
      - draft
      - active
      - paused
      - suspended
      - completed
    Funnel:
      type: object
      required:
      - id
      - name
      - status
      properties:
        id:
          $ref: '#/components/schemas/Uuid'
        name:
          type: string
          examples:
          - Willkommensstrecke Neukunden
        status:
          $ref: '#/components/schemas/FunnelStatus'
        segmentId:
          type:
          - string
          - 'null'
          format: uuid
        mailboxId:
          type:
          - string
          - 'null'
          format: uuid
        stats:
          type: object
          properties:
            enrolled:
              type: integer
            sent:
              type: integer
            delivered:
              type: integer
            opened:
              type: integer
            clicked:
              type: integer
            unsubscribed:
              type: integer
        activatedAt:
          type:
          - string
          - 'null'
          format: date-time
    Enrollment:
      type: object
      required:
      - id
      - subjectType
      - subjectId
      - status
      - startedAt
      properties:
        id:
          $ref: '#/components/schemas/Uuid'
        subjectType:
          type: string
          enum:
          - contact
          - lead
        subjectId:
          $ref: '#/components/schemas/Uuid'
        status:
          type: string
          enum:
          - pending
          - active
          - in_progress
          - completed
          - failed
          - cancelled
          - unsubscribed
        currentStep:
          type:
          - string
          - 'null'
        startedAt:
          type: string
          format: date-time
        finishedAt:
          type:
          - string
          - 'null'
          format: date-time
    EmailOptOut:
      type: object
      required:
      - email
      - unsubscribedAt
      properties:
        email:
          type: string
          format: email
        contactId:
          type:
          - string
          - 'null'
          format: uuid
        reason:
          type:
          - string
          - 'null'
        unsubscribedAt:
          type: string
          format: date-time
    AutomationTrigger:
      type: string
      enum:
      - contact_created
      - contact_updated
      - contact_tag_added
      - contact_tag_removed
      - contact_label_changed
      - lead_created
      - lead_converted
      - lead_stage_changed
      - task_created
      - task_status_changed
      - email_received
      - email_sent
      - date_field_reached
      - contract_expiring
      - manual
      - api
    Automation:
      type: object
      required:
      - id
      - name
      - status
      - trigger
      properties:
        id:
          $ref: '#/components/schemas/Uuid'
        name:
          type: string
          examples:
          - Ablaufende Verträge nachfassen
        status:
          type: string
          enum:
          - draft
          - active
          - paused
          - completed
        trigger:
          $ref: '#/components/schemas/AutomationTrigger'
        subject:
          type: string
          enum:
          - contact
          - lead
          - task
        stats:
          type: object
          properties:
            active:
              type: integer
            completed:
              type: integer
            failed:
              type: integer
        updatedAt:
          type: string
          format: date-time
    Calculator:
      type: object
      required:
      - slug
      - name
      properties:
        slug:
          type: string
          examples:
          - rentenluecke
        name:
          type: string
          examples:
          - Rentenlücke
        description:
          type:
          - string
          - 'null'
        category:
          type:
          - string
          - 'null'
          examples:
          - Altersvorsorge
        contactSlots:
          type: array
          description: Which contacts the calculator works with.
          items:
            type: string
            enum:
            - main_contact
            - partner
            - child
            - company
        usableInPortal:
          type: boolean
    Calculation:
      type: object
      required:
      - id
      - calculator
      - contactId
      - data
      - createdAt
      properties:
        id:
          $ref: '#/components/schemas/Uuid'
        calculator:
          type: object
          required:
          - slug
          - name
          properties:
            slug:
              type: string
            name:
              type: string
        contactId:
          $ref: '#/components/schemas/Uuid'
        data:
          type: object
          description: Inputs and results, structured according to the calculator's `resultSchema`.
          additionalProperties: true
        savedByCustomerAt:
          type:
          - string
          - 'null'
          format: date-time
          description: Set when the customer saved it in the portal.
        createdBy:
          oneOf:
          - $ref: '#/components/schemas/UserRef'
          - type: 'null'
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type:
          - string
          - 'null'
          format: date-time
    AdviceRecordInput:
      type: object
      properties:
        contactId:
          $ref: '#/components/schemas/Uuid'
        consultedAt:
          type: string
          format: date-time
        channel:
          type: string
          enum:
          - in_person
          - phone
          - video
          - email
        topics:
          type: array
          items:
            $ref: '#/components/schemas/ContractType'
        customerWishes:
          type: string
          maxLength: 10000
        needsAnalysis:
          type: string
          maxLength: 10000
        recommendation:
          type: string
          maxLength: 10000
        reasoning:
          type: string
          maxLength: 10000
          description: Why the recommended product fits (Begründung).
        decision:
          type: string
          enum:
          - accepted
          - partially_accepted
          - declined
          - postponed
        adviceWaiver:
          type: boolean
          default: false
          description: Customer waived advice in writing (Beratungsverzicht).
        relatedContractIds:
          type: array
          items:
            $ref: '#/components/schemas/Uuid'
        calculationIds:
          type: array
          items:
            $ref: '#/components/schemas/Uuid'
    AdviceRecord:
      allOf:
      - type: object
        required:
        - id
        - contactId
        - consultedAt
        - status
        properties:
          id:
            $ref: '#/components/schemas/Uuid'
          status:
            type: string
            enum:
            - draft
            - documented
            - signed
          documentId:
            type:
            - string
            - 'null'
            format: uuid
          advisor:
            oneOf:
            - $ref: '#/components/schemas/UserRef'
            - type: 'null'
      - $ref: '#/components/schemas/AdviceRecordInput'
      - $ref: '#/components/schemas/Timestamps'
    ImportJob:
      type: object
      required:
      - id
      - status
      - filename
      - createdAt
      properties:
        id:
          $ref: '#/components/schemas/Uuid'
        filename:
          type: string
          examples:
          - kunden_export.csv
        status:
          type: string
          enum:
          - analyzing
          - analyzed
          - importing
          - completed
          - failed
        contactType:
          $ref: '#/components/schemas/ContactType'
        suggestedMapping:
          type: object
          additionalProperties:
            type: string
          examples:
          - Vorname: firstName
            Nachname: lastName
            PLZ: address.zipCode
        rows:
          type: object
          properties:
            total:
              type: integer
            created:
              type: integer
            updated:
              type: integer
            duplicate:
              type: integer
            failed:
              type: integer
        createdAt:
          type: string
          format: date-time
        completedAt:
          type:
          - string
          - 'null'
          format: date-time
    PrivacyRequest:
      type: object
      required:
      - id
      - type
      - contactId
      - status
      - createdAt
      properties:
        id:
          $ref: '#/components/schemas/Uuid'
        type:
          type: string
          enum:
          - data_export
          - erasure
        contactId:
          $ref: '#/components/schemas/Uuid'
        status:
          type: string
          enum:
          - queued
          - processing
          - completed
          - partially_blocked
          - failed
        downloadUrl:
          type:
          - string
          - 'null'
          format: uri
          description: For `data_export`, valid for 7 days.
        blockedUntil:
          type:
          - string
          - 'null'
          format: date
          description: 'For `erasure`: end of the longest retention period.'
        createdAt:
          type: string
          format: date-time
        completedAt:
          type:
          - string
          - 'null'
          format: date-time
    CustomFieldDefinitionInput:
      type: object
      properties:
        label:
          type: string
          maxLength: 255
        type:
          type: string
          enum:
          - string
          - number
          - date
          - boolean
          - select
          - multiselect
        contactTypes:
          type: array
          minItems: 1
          items:
            $ref: '#/components/schemas/ContactType'
        required:
          type: boolean
        searchable:
          type: boolean
        options:
          type: array
          items:
            type: string
        validation:
          type: object
          properties:
            min:
              type: number
            max:
              type: number
            minLength:
              type: integer
            maxLength:
              type: integer
            pattern:
              type: string
        category:
          type:
          - string
          - 'null'