> ## Documentation Index
> Fetch the complete documentation index at: https://docs.intermezzo.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Update Employee Insurance Details

> Update insurance details for an employee (creates new version).



## OpenAPI

````yaml /api-reference/preview.json put /organizations/{organization_id}/employees/{employee_id}/insurance-details
openapi: 3.1.0
info:
  title: FastAPI
  version: 0.1.0
servers: []
security: []
paths:
  /organizations/{organization_id}/employees/{employee_id}/insurance-details:
    put:
      tags:
        - Core
        - Employees
        - Insurance Details
      summary: Update Employee Insurance Details
      description: Update insurance details for an employee (creates new version).
      operationId: >-
        update_employee_insurance_details_organizations__organization_id__employees__employee_id__insurance_details_put
      parameters:
        - name: organization_id
          in: path
          required: true
          schema:
            anyOf:
              - type: string
              - type: string
                format: uuid
            title: Organization Id
        - name: employee_id
          in: path
          required: true
          schema:
            anyOf:
              - type: string
              - type: string
                format: uuid
            title: Employee Id
      requestBody:
        required: true
        content:
          application/json:
            schema:
              oneOf:
                - $ref: >-
                    #/components/schemas/payroll__de__schema__employee__InsuranceDetails
                - $ref: >-
                    #/components/schemas/payroll__gb__schema__employee__InsuranceDetails
              discriminator:
                propertyName: employment_country
                mapping:
                  DE:
                    $ref: >-
                      #/components/schemas/payroll__de__schema__employee__InsuranceDetails
                  GB:
                    $ref: >-
                      #/components/schemas/payroll__gb__schema__employee__InsuranceDetails
              title: Insurance Details
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                oneOf:
                  - $ref: >-
                      #/components/schemas/payroll__de__schema__employee__InsuranceDetailsResponse
                  - $ref: >-
                      #/components/schemas/payroll__gb__schema__employee__InsuranceDetailsResponse
                discriminator:
                  propertyName: employment_country
                  mapping:
                    DE:
                      $ref: >-
                        #/components/schemas/payroll__de__schema__employee__InsuranceDetailsResponse
                    GB:
                      $ref: >-
                        #/components/schemas/payroll__gb__schema__employee__InsuranceDetailsResponse
                title: >-
                  Response Update Employee Insurance Details Organizations 
                  Organization Id  Employees  Employee Id  Insurance Details Put
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
        - BearerToken: []
components:
  schemas:
    payroll__de__schema__employee__InsuranceDetails:
      properties:
        employment_country:
          type: string
          const: DE
          title: Employment Country
          default: DE
        insurance_number:
          anyOf:
            - type: string
              description: >-
                German Versicherungsnummer (12 chars:
                region-birthdate-name-serial-check). Validates according to VKVV
                § 2. See: https://www.gesetze-im-internet.de/vkvv/__2.html
              examples:
                - 12345678A123
                - 29041275B507
            - type: 'null'
          title: Insurance Number
          description: 'EN: Health insurance number | DE: Versicherungsnummer'
        contribution_group:
          anyOf:
            - type: string
              maxLength: 4
              minLength: 4
            - type: 'null'
          title: Contribution Group
          description: 'EN: Contribution group | DE: Beitragsgruppe'
        person_group:
          anyOf:
            - $ref: '#/components/schemas/PersonGroup'
            - type: 'null'
          description: 'EN: Person group | DE: Personengruppe'
        insurance_provider:
          anyOf:
            - type: string
            - type: 'null'
          title: Insurance Provider
          description: 'EN: Health insurance provider | DE: Krankenkasse'
        alternate_collection_agency:
          anyOf:
            - type: string
            - type: 'null'
          title: Alternate Collection Agency
          description: 'EN: Alternate collection agency | DE: Einzugsstelle'
        private_insurance_health_monthly:
          anyOf:
            - type: number
              minimum: 0
            - type: string
              pattern: ^(?!^[-+.]*$)[+-]?0*\d*\.?\d{0,2}0*$
            - type: 'null'
          title: Private Insurance Health Monthly
          description: >-
            EN:Private health insurance monthly|DE:Private Krankenversicherung
            monatlich
          default: '0'
        private_insurance_care_monthly:
          anyOf:
            - type: number
              minimum: 0
            - type: string
              pattern: ^(?!^[-+.]*$)[+-]?0*\d*\.?\d{0,2}0*$
            - type: 'null'
          title: Private Insurance Care Monthly
          description: >-
            EN: Private care insurance monthly | DE: Private Pflegeversicherung
            monatlich
          default: '0'
        care_insurance_children:
          anyOf:
            - type: integer
              maximum: 5
              minimum: 0
            - type: 'null'
          title: Care Insurance Children
          description: 'EN: Children for care insurance | DE: Kinder für Pflegeversicherung'
          default: 0
        u1_exempt:
          anyOf:
            - type: boolean
            - type: 'null'
          title: U1 Exempt
          description: 'EN: U1 exemption | DE: U1 Befreiung'
        u2_exempt:
          anyOf:
            - type: boolean
            - type: 'null'
          title: U2 Exempt
          description: 'EN: U2 exemption | DE: U2 Befreiung'
        uv_risk_tariff:
          anyOf:
            - items:
                $ref: '#/components/schemas/RiskTariff-Input'
              type: array
            - type: 'null'
          title: Uv Risk Tariff
          description: 'EN: UV risk tariff details | DE: UV-Risikotarifdetails'
        pension_details:
          anyOf:
            - $ref: '#/components/schemas/PensionDetails'
            - type: 'null'
          description: >-
            EN: Pension details for Annex 04a validation | DE: Rentendetails für
            Anlage 04a-Prüfung
        valid_from:
          anyOf:
            - type: string
              format: date
            - type: 'null'
          title: Valid From
          description: 'EN: Valid from date | DE: Gültig ab Datum'
        valid_to:
          anyOf:
            - type: string
              format: date
            - type: 'null'
          title: Valid To
          description: 'EN: Valid to date | DE: Gültig bis Datum'
        birth_date_context:
          anyOf:
            - type: string
              format: date
            - type: 'null'
          title: Birth Date Context
      additionalProperties: true
      type: object
      title: InsuranceDetails
    payroll__gb__schema__employee__InsuranceDetails:
      properties:
        employment_country:
          type: string
          const: GB
          title: Employment Country
          default: GB
        insurance_number:
          anyOf:
            - type: string
              maxLength: 9
              minLength: 9
            - type: 'null'
          title: Insurance Number
          description: 'EN: Health insurance number | DE: Versicherungsnummer'
        insurance_category:
          $ref: '#/components/schemas/NICCategory'
        valid_from:
          anyOf:
            - type: string
              format: date
            - type: 'null'
          title: Valid From
          description: 'EN: Valid from date | DE: Gültig ab Datum'
        valid_to:
          anyOf:
            - type: string
              format: date
            - type: 'null'
          title: Valid To
          description: 'EN: Valid to date | DE: Gültig bis Datum'
      additionalProperties: true
      type: object
      required:
        - insurance_category
      title: InsuranceDetails
    payroll__de__schema__employee__InsuranceDetailsResponse:
      properties:
        employee_id:
          type: string
          title: Employee Id
        created_at:
          type: string
          format: date-time
          title: Created At
        updated_at:
          type: string
          format: date-time
          title: Updated At
        id:
          anyOf:
            - type: string
            - type: string
              format: uuid
          title: Id
        employment_country:
          type: string
          const: DE
          title: Employment Country
          default: DE
        insurance_number:
          anyOf:
            - type: string
            - type: 'null'
          title: Insurance Number
        contribution_group:
          anyOf:
            - type: string
            - type: 'null'
          title: Contribution Group
        person_group:
          anyOf:
            - $ref: '#/components/schemas/PersonGroup'
            - type: 'null'
        insurance_provider:
          anyOf:
            - type: string
            - type: 'null'
          title: Insurance Provider
        alternate_collection_agency:
          anyOf:
            - type: string
            - type: 'null'
          title: Alternate Collection Agency
        private_insurance_health_monthly:
          anyOf:
            - type: string
              pattern: ^(?!^[-+.]*$)[+-]?0*\d*\.?\d{0,2}0*$
            - type: 'null'
          title: Private Insurance Health Monthly
          description: >-
            EN:Private health insurance monthly|DE:Private Krankenversicherung
            monatlich
          default: '0'
        private_insurance_care_monthly:
          anyOf:
            - type: string
              pattern: ^(?!^[-+.]*$)[+-]?0*\d*\.?\d{0,2}0*$
            - type: 'null'
          title: Private Insurance Care Monthly
          description: >-
            EN: Private care insurance monthly | DE: Private Pflegeversicherung
            monatlich
          default: '0'
        care_insurance_children:
          anyOf:
            - type: integer
            - type: 'null'
          title: Care Insurance Children
          default: 0
        u1_exempt:
          anyOf:
            - type: boolean
            - type: 'null'
          title: U1 Exempt
          default: false
        u2_exempt:
          anyOf:
            - type: boolean
            - type: 'null'
          title: U2 Exempt
          default: false
        uv_risk_tariff:
          anyOf:
            - items:
                $ref: '#/components/schemas/RiskTariff-Output'
              type: array
            - type: 'null'
          title: Uv Risk Tariff
        pension_details:
          anyOf:
            - $ref: '#/components/schemas/PensionDetails'
            - type: 'null'
        valid_from:
          anyOf:
            - type: string
              format: date
            - type: 'null'
          title: Valid From
          description: 'EN: Valid from date | DE: Gültig ab Datum'
        valid_to:
          anyOf:
            - type: string
              format: date
            - type: 'null'
          title: Valid To
          description: 'EN: Valid to date | DE: Gültig bis Datum'
      additionalProperties: true
      type: object
      required:
        - employee_id
        - created_at
        - updated_at
        - id
      title: InsuranceDetailsResponse
      description: Response model for insurance details with metadata fields.
    payroll__gb__schema__employee__InsuranceDetailsResponse:
      properties:
        employee_id:
          type: string
          title: Employee Id
        created_at:
          anyOf:
            - type: string
              format: date-time
            - type: 'null'
          title: Created At
        updated_at:
          anyOf:
            - type: string
              format: date-time
            - type: 'null'
          title: Updated At
        id:
          anyOf:
            - type: string
            - type: string
              format: uuid
          title: Id
        employment_country:
          type: string
          const: GB
          title: Employment Country
          default: GB
        insurance_number:
          anyOf:
            - type: string
            - type: 'null'
          title: Insurance Number
        insurance_category:
          $ref: '#/components/schemas/NICCategory'
        valid_from:
          anyOf:
            - type: string
              format: date
            - type: 'null'
          title: Valid From
          description: 'EN: Valid from date | DE: Gültig ab Datum'
        valid_to:
          anyOf:
            - type: string
              format: date
            - type: 'null'
          title: Valid To
          description: 'EN: Valid to date | DE: Gültig bis Datum'
      additionalProperties: true
      type: object
      required:
        - employee_id
        - created_at
        - updated_at
        - id
        - insurance_category
      title: InsuranceDetailsResponse
      description: Response model for insurance details with metadata fields.
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    PersonGroup:
      type: integer
      enum:
        - 101
        - 102
        - 103
        - 104
        - 105
        - 106
        - 107
        - 108
        - 109
        - 110
        - 111
        - 112
        - 113
        - 114
        - 116
        - 117
        - 118
        - 119
        - 120
        - 121
        - 122
        - 123
        - 124
        - 127
        - 190
        - 140
        - 141
        - 142
        - 143
        - 144
        - 149
        - 150
        - 203
        - 204
        - 207
        - 208
        - 209
        - 210
        - 301
        - 302
        - 303
        - 304
        - 305
        - 306
        - 307
      title: PersonGroup
      description: >-
        An IntEnum representing the key numbers ('Schlüsselzahlen') for person
        groups

        in German social insurance notifications (DEÜV).
    RiskTariff-Input:
      properties:
        tariff_code:
          anyOf:
            - type: string
            - type: 'null'
          title: Tariff Code
          description: 'EN: UV risk tariff code | DE: UV-Risikotarifcode'
        tariff_description:
          anyOf:
            - type: string
            - type: 'null'
          title: Tariff Description
          description: 'EN: UV risk tariff description | DE: UV-Risikotarifbeschreibung'
        tariff_percentage:
          anyOf:
            - type: number
            - type: string
              pattern: ^(?!^[-+.]*$)[+-]?0*\d*\.?\d*$
            - type: 'null'
          title: Tariff Percentage
          description: 'EN: UV risk tariff percentage | DE: UV-Risikotarifprozentsatz'
          default: '0'
      additionalProperties: true
      type: object
      title: RiskTariff
      description: Schema for UV risk tariff details of a German employee.
    PensionDetails:
      properties:
        employment_country:
          type: string
          const: DE
          title: Employment Country
          default: DE
        received_mining_adjustment_payments:
          type: boolean
          title: Received Mining Adjustment Payments
          description: >-
            EN: Receipt of adjustment payments for dismissed mining employees |
            DE: Anpassungsgeld-Bezug
          default: false
        pension_type:
          anyOf:
            - $ref: '#/components/schemas/PensionType'
            - type: 'null'
          description: >-
            EN: Type of pension received (due to age) | DE: Art der Rente (wegen
            Alters)
        pension_start_date:
          anyOf:
            - type: string
              format: date
            - type: 'null'
          title: Pension Start Date
          description: >-
            EN: Pension start date according to pension notice | DE:
            Rentenbeginn laut Rentenbescheid
        waiver_declaration_status:
          $ref: '#/components/schemas/WaiverDeclarationStatus'
          description: >-
            EN: Waiver of pension insurance exemption declaration | DE:
            Verzichtserklärung Versicherungsfreiheit RV
          default: default
        waiver_receipt_date:
          anyOf:
            - type: string
              format: date
            - type: 'null'
          title: Waiver Receipt Date
          description: >-
            EN: Date employer received waiver declaration | DE: Eingang
            Verzichtserklärung beim Arbeitgeber
        waiver_validity_date:
          anyOf:
            - type: string
              format: date
            - type: 'null'
          title: Waiver Validity Date
          description: 'EN: Date from which waiver is valid | DE: Verzicht gültig ab'
      additionalProperties: true
      type: object
      title: PensionDetails
      description: >-
        Pension details for German employees according to Annex 04a
        specification.

        Required for extended plausibility checks of employed pensioners.
    NICCategory:
      type: string
      enum:
        - A
        - B
        - C
        - D
        - E
        - F
        - H
        - I
        - J
        - K
        - L
        - M
        - 'N'
        - S
        - V
        - X
        - Z
      title: NICCategory
      description: NIC Letter Categories
    RiskTariff-Output:
      properties:
        tariff_code:
          anyOf:
            - type: string
            - type: 'null'
          title: Tariff Code
          description: 'EN: UV risk tariff code | DE: UV-Risikotarifcode'
        tariff_description:
          anyOf:
            - type: string
            - type: 'null'
          title: Tariff Description
          description: 'EN: UV risk tariff description | DE: UV-Risikotarifbeschreibung'
        tariff_percentage:
          anyOf:
            - type: string
              pattern: ^(?!^[-+.]*$)[+-]?0*\d*\.?\d*$
            - type: 'null'
          title: Tariff Percentage
          description: 'EN: UV risk tariff percentage | DE: UV-Risikotarifprozentsatz'
          default: '0'
      additionalProperties: true
      type: object
      title: RiskTariff
      description: Schema for UV risk tariff details of a German employee.
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
              - type: string
              - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
      type: object
      required:
        - loc
        - msg
        - type
      title: ValidationError
    PensionType:
      type: string
      enum:
        - full_old_age_pension_eu_eea_sva
        - full_pension_civil_service
        - partial_old_age_pension
        - partial_pension_civil_service
        - full_old_age_pension_non_eu
        - full_pension_reduced_earning_capacity
      title: PensionType
      description: |-
        Pension types according to Annex 04a specification for extended checks.
        Priority order is important - higher listed types take precedence.
    WaiverDeclarationStatus:
      type: string
      enum:
        - default
        - 'yes'
        - 'no'
      title: WaiverDeclarationStatus
      description: Status of pension insurance exemption waiver declaration.
  securitySchemes:
    BearerToken:
      type: oauth2
      flows:
        password:
          scopes:
            read:all: Read all
            write:all: Write all
            read:health_check: Read health check
            write:health_check: Write health check
            read:wage_types: Read wage types
            write:wage_types: Write wage types
          tokenUrl: >-
            https://auth-preview.intermezzo.ai/authorize?audience=api-preview.intermezzo.ai

````