> ## 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.

# Run Payroll



## OpenAPI

````yaml /api-reference/openapi.json post /germany/payroll
openapi: 3.1.0
info:
  title: Intermezzo Global Payroll
  summary: Global Payroll Platform
  description: Intermezzo's global payroll apis, organized by country
  version: 1.0.0
  x-logo:
    url: /static/icon.svg
servers:
  - url: https://sandbox.intermezzo.ai
    description: Sandbox
security: []
paths:
  /germany/payroll:
    post:
      tags:
        - Germany Paycheck Calculator
      summary: Run Payroll
      operationId: new_payroll_germany_payroll_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: >-
                #/components/schemas/payroll__germany__schema__request__PayrollRequest
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: >-
                  #/components/schemas/payroll__germany__schema__response__PayrollResponse
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
        - BearerToken: []
components:
  schemas:
    payroll__germany__schema__request__PayrollRequest:
      properties:
        payDate:
          type: string
          format: date
          title: Paydate
          description: Payment Date for this payroll
        payCycle:
          $ref: '#/components/schemas/PayCycleType-Input'
        payrollGroup:
          items:
            $ref: >-
              #/components/schemas/payroll__germany__schema__request__PayrollRequestBase
          type: array
          title: Payrollgroup
      additionalProperties: false
      type: object
      required:
        - payCycle
        - payrollGroup
      title: PayrollRequest
      description: Input parameters according to PAP2025
    payroll__germany__schema__response__PayrollResponse:
      properties:
        summary:
          $ref: '#/components/schemas/Summary'
        payslips:
          items:
            $ref: '#/components/schemas/payroll__germany__schema__response__Payslip'
          type: array
          title: Payslips
      additionalProperties: false
      type: object
      required:
        - payslips
      title: PayrollResponse
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    PayCycleType-Input:
      type: string
      enum:
        - Year
        - Month
        - Week
        - Day
      title: PayCycleType
      description: Lohnzahlungszeitraum (LZZ)
    payroll__germany__schema__request__PayrollRequestBase:
      properties:
        employeeDetails:
          $ref: '#/components/schemas/EmployeeDetails'
        taxAttributes:
          $ref: '#/components/schemas/TaxAttributes'
        insuranceDetails:
          $ref: >-
            #/components/schemas/payroll__germany__schema__request__InsuranceDetails
        payDetails:
          $ref: '#/components/schemas/payroll__germany__schema__request__Gross'
      additionalProperties: false
      type: object
      required:
        - employeeDetails
        - taxAttributes
        - insuranceDetails
        - payDetails
      title: PayrollRequestBase
      description: Input parameters
    Summary:
      properties:
        employer:
          $ref: '#/components/schemas/EmployerSummary'
      additionalProperties: false
      type: object
      title: Summary
    payroll__germany__schema__response__Payslip:
      properties:
        paymentPeriod:
          $ref: '#/components/schemas/payroll__germany__payroll_types__PayCycleType'
          default: Month
        employeeId:
          type: integer
          title: Employeeid
        currentPayPeriod:
          $ref: >-
            #/components/schemas/payroll__germany__schema__response__CurrentPayPeriod
      additionalProperties: false
      type: object
      required:
        - employeeId
        - currentPayPeriod
      title: Payslip
    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
    EmployeeDetails:
      properties:
        employeeId:
          type: integer
          title: Employeeid
          description: Mitarbeiterkennzeichen - Employee identification number
        isMiniJob:
          type: boolean
          title: Isminijob
          description: Whether the employee is a mini-jobber
          default: false
        miniJobDetails:
          anyOf:
            - $ref: '#/components/schemas/MiniJobDetails'
            - type: 'null'
          description: Mini-job specific details (required when is_mini_job is True)
        yearOfBirth:
          type: integer
          maximum: 2025
          minimum: 1850
          title: Yearofbirth
          description: >-
            Geburtsjahr - Birth Year to check eligibility for
            Altersentlastungsbetrag
        agreedWorkHoursPerWeek:
          anyOf:
            - type: number
              minimum: 0
            - type: string
          title: Agreedworkhoursperweek
          description: Agreed work hours per week
          default: '0'
      additionalProperties: false
      type: object
      required:
        - employeeId
        - yearOfBirth
      title: EmployeeDetails
    TaxAttributes:
      properties:
        taxClass:
          $ref: '#/components/schemas/TaxClassType'
          description: Steuerklasse (STKL) - Tax class
        isFactor:
          anyOf:
            - type: boolean
            - type: 'null'
          title: Isfactor
          description: Faktorverfahren (AF) - Factor procedure flag (only for tax class IV)
          default: false
        factor:
          anyOf:
            - type: number
              multipleOf: 0.001
              exclusiveMaximum: 1
              minimum: 0.001
            - type: string
            - type: 'null'
          title: Factor
          description: Faktor (F) - Factor for factor procedure
        childAllowances:
          anyOf:
            - type: number
              multipleOf: 0.5
              maximum: 9
              minimum: 0
            - type: string
          title: Childallowances
          description: >-
            Kinderfreibeträge (ZKF) - Number of child allowances (decimal place
            for shared allowances)
          default: '0'
        isChurchMember:
          type: boolean
          title: Ischurchmember
          description: Religionsgemeinschaft (R) - Church membership
          default: false
        taxState:
          anyOf:
            - $ref: '#/components/schemas/GermanStates'
            - type: 'null'
          description: Bundesländer - Residency state
          default: Berlin
      additionalProperties: false
      type: object
      required:
        - taxClass
      title: TaxAttributes
    payroll__germany__schema__request__InsuranceDetails:
      properties:
        pensionInsuranceType:
          $ref: '#/components/schemas/PensionInsuranceType'
          description: Rentenversicherung (KRV) - Pension insurance type
        healthInsuranceType:
          $ref: '#/components/schemas/HealthInsuranceType'
          description: Krankenversicherung (PKV) - Health insurance type
        healthInsurerAgencyCode:
          anyOf:
            - type: string
            - type: 'null'
          title: Healthinsureragencycode
          description: Krankenversicherungscode (KVK) - Health insurer agency code
        privateInsuranceMonthly:
          anyOf:
            - type: number
              minimum: 0
            - type: string
            - type: 'null'
          title: Privateinsurancemonthly
          description: >-
            Private Krankenversicherung (PKPV) - Monthly private health/care
            insurance contribution
          default: '0'
        careInsuranceChildren:
          type: integer
          maximum: 5
          minimum: 0
          title: Careinsurancechildren
          description: >-
            Anzahl Kinder Pflegeversicherung (PVA) - Number of children for care
            insurance discount (0-5), choose 5 for 5 or more
          default: 0
        isMidiJob:
          type: boolean
          title: Ismidijob
          description: Whether the employee is a midi-jobber
          default: false
      additionalProperties: false
      type: object
      required:
        - pensionInsuranceType
        - healthInsuranceType
      title: InsuranceDetails
    payroll__germany__schema__request__Gross:
      properties:
        earnings:
          anyOf:
            - items:
                oneOf:
                  - $ref: '#/components/schemas/SalariedEarnings'
                  - $ref: '#/components/schemas/HourlyEarnings'
                  - $ref: '#/components/schemas/OtherEarnings'
              type: array
            - type: 'null'
          title: Earnings
        benefits:
          anyOf:
            - items:
                oneOf:
                  - $ref: '#/components/schemas/Car'
                  - $ref: '#/components/schemas/NonCarBenefits'
                discriminator:
                  propertyName: name
                  mapping:
                    Allowances:
                      $ref: '#/components/schemas/NonCarBenefits'
                    Capital-forming:
                      $ref: '#/components/schemas/NonCarBenefits'
                    Company Car:
                      $ref: '#/components/schemas/Car'
                    Company Pension:
                      $ref: '#/components/schemas/NonCarBenefits'
                    Gym:
                      $ref: '#/components/schemas/NonCarBenefits'
                    Meal Plan:
                      $ref: '#/components/schemas/NonCarBenefits'
                    Other:
                      $ref: '#/components/schemas/NonCarBenefits'
              type: array
            - type: 'null'
          title: Benefits
        deductions:
          anyOf:
            - items:
                $ref: >-
                  #/components/schemas/payroll__germany__schema__request__Deductions
              type: array
            - type: 'null'
          title: Deductions
        reimbursements:
          anyOf:
            - items:
                $ref: >-
                  #/components/schemas/payroll__germany__schema__request__Reimbursement
              type: array
            - type: 'null'
          title: Reimbursements
      additionalProperties: false
      type: object
      required:
        - earnings
        - benefits
      title: Gross
    EmployerSummary:
      properties:
        pensionContribution:
          type: string
          title: Pensioncontribution
          default: '0.00'
        healthInsuranceContribution:
          type: string
          title: Healthinsurancecontribution
          default: '0.00'
        careInsuranceContribution:
          type: string
          title: Careinsurancecontribution
          default: '0.00'
        unemploymentInsuranceContribution:
          type: string
          title: Unemploymentinsurancecontribution
          default: '0.00'
        sickPayInsuranceContribution:
          type: string
          title: Sickpayinsurancecontribution
          default: '0.00'
        maternityPayInsuranceContribution:
          type: string
          title: Maternitypayinsurancecontribution
          default: '0.00'
        insolvencyInsuranceContribution:
          type: string
          title: Insolvencyinsurancecontribution
          default: '0.00'
        flatRateTaxMiniJob:
          type: string
          title: Flatratetaxminijob
          default: '0.00'
        totalBurden:
          type: string
          title: Totalburden
          default: '0.00'
      additionalProperties: false
      type: object
      title: EmployerSummary
    payroll__germany__payroll_types__PayCycleType:
      type: string
      enum:
        - Year
        - Month
        - Week
        - Day
      title: PayCycleType
      description: Lohnzahlungszeitraum (LZZ)
    payroll__germany__schema__response__CurrentPayPeriod:
      properties:
        employee:
          $ref: >-
            #/components/schemas/payroll__germany__schema__response__EmployeeCurrentPayPeriod
        employer:
          $ref: >-
            #/components/schemas/payroll__germany__schema__response__EmployerCurrentPayPeriod
      additionalProperties: false
      type: object
      title: CurrentPayPeriod
    MiniJobDetails:
      properties:
        miniJobType:
          $ref: '#/components/schemas/MiniJobType'
          description: 'Type of mini-job: short-term or earning-limit based'
        taxMethod:
          $ref: '#/components/schemas/MiniJobTaxMethod'
          description: 'Tax method for mini-jobs: flat rate or individual taxation'
        pensionExemption:
          type: boolean
          title: Pensionexemption
          description: Whether the mini-jobber is exempt from pension insurance
          default: false
        flatRatePaidByEmployee:
          type: boolean
          title: Flatratepaidbyemployee
          description: >-
            Whether the 2% flat rate tax is paid by the employee instead of the
            employer
          default: false
        shortTermFlatTaxRate:
          anyOf:
            - type: integer
              enum:
                - 20
                - 25
            - type: 'null'
          title: Shorttermflattaxrate
          description: |2-

                        The flat tax rate for short-term mini-jobs.
                        Required if mini_job_type is 'Short Term' and tax_method is 'Flat Rate'.
                        Can be 20% or 25%.
                    
      additionalProperties: false
      type: object
      required:
        - miniJobType
        - taxMethod
      title: MiniJobDetails
      description: Details for mini-job classification and processing
    TaxClassType:
      type: string
      enum:
        - '1'
        - '2'
        - '3'
        - '4'
        - '5'
        - '6'
      title: TaxClassType
      description: Steuerklasse (STKL)
    GermanStates:
      type: string
      enum:
        - Baden-Württemberg
        - Bayern
        - Berlin
        - Brandenburg
        - Bremen
        - Hamburg
        - Hessen
        - Mecklenburg-Vorpommern
        - Niedersachsen
        - Nordrhein-Westfalen
        - Rheinland-Pfalz
        - Saarland
        - Sachsen
        - Sachsen-Anhalt
        - Schleswig-Holstein
        - Thüringen
      title: GermanStates
      description: German states (Bundesländer) with their official names
    PensionInsuranceType:
      type: string
      enum:
        - Statutory
        - Other
      title: PensionInsuranceType
      description: Merker für die Vorsorgepauschale (KRV)
    HealthInsuranceType:
      type: string
      enum:
        - Statutory KV
        - Private KV without employer subsidy
        - Private KV with employer subsidy
      title: HealthInsuranceType
      description: Krankenversicherungsart (PKV)
    SalariedEarnings:
      properties:
        earningType:
          type: string
          const: Salary
          title: Earningtype
        amount:
          anyOf:
            - type: number
              minimum: 0
            - type: string
          title: Amount
          description: Earnings amount (taxable gross)
        earningFrequency:
          anyOf:
            - $ref: '#/components/schemas/PayCycleType-Input'
            - type: 'null'
          description: If recurring, specify the frequency
          default: Month
        isLumpsum:
          anyOf:
            - type: boolean
            - type: 'null'
          title: Islumpsum
          description: True if onetime (Einmalig). False if recurring (Laufend)
          default: false
        doGrossup:
          anyOf:
            - type: boolean
            - type: 'null'
          title: Dogrossup
          description: True if the amount needs to be grossed up
          default: false
      additionalProperties: false
      type: object
      required:
        - earningType
        - amount
      title: SalariedEarnings
    HourlyEarnings:
      properties:
        earningType:
          type: string
          enum:
            - Holiday Work
            - Hourly Wage
            - Increased Night Shift
            - Night Shift
            - Special Holiday Work
            - Sunday Work
          title: Earningtype
        hoursWorked:
          anyOf:
            - type: number
              minimum: 0
            - type: string
          title: Hoursworked
          description: Number of hours worked
        hourlyRate:
          anyOf:
            - type: number
              minimum: 0
            - type: string
          title: Hourlyrate
          description: Hourly rate in euros
      additionalProperties: false
      type: object
      required:
        - earningType
        - hoursWorked
        - hourlyRate
      title: HourlyEarnings
    OtherEarnings:
      properties:
        earningType:
          type: string
          enum:
            - Commissions
            - Bonus
            - Allowances
            - Other
          title: Earningtype
        amount:
          anyOf:
            - type: number
              minimum: 0
            - type: string
          title: Amount
          description: Earnings amount
        earningFrequency:
          anyOf:
            - $ref: '#/components/schemas/PayCycleType-Input'
            - type: 'null'
          description: If recurring, specify the frequency
          default: Month
        isLumpsum:
          anyOf:
            - type: boolean
            - type: 'null'
          title: Islumpsum
          description: True if onetime (Einmalig). False if recurring (Laufend)
          default: false
        doGrossup:
          anyOf:
            - type: boolean
            - type: 'null'
          title: Dogrossup
          description: True if the amount needs to be grossed up
          default: false
      additionalProperties: false
      type: object
      required:
        - earningType
        - amount
      title: OtherEarnings
    Car:
      properties:
        name:
          type: string
          const: Company Car
          title: Name
        value:
          anyOf:
            - type: number
              minimum: 0
            - type: string
            - type: 'null'
          title: Value
          description: Cost of car
        additionalPayments:
          anyOf:
            - type: number
            - type: string
            - type: 'null'
          title: Additionalpayments
          description: Zuzahl. Firmenw. stpfl.
          default: '0.00'
        privateTrip:
          anyOf:
            - type: number
              minimum: 0
            - type: string
            - type: 'null'
          title: Privatetrip
          description: Privatfahrten
          default: '0.00'
      additionalProperties: false
      type: object
      required:
        - name
      title: Car
    NonCarBenefits:
      properties:
        name:
          anyOf:
            - type: string
              const: Company Pension
            - type: string
              const: Capital-forming
            - type: string
              const: Allowances
            - type: string
              const: Meal Plan
            - type: string
              const: Gym
            - type: string
              const: Other
          title: Name
        employeeShare:
          anyOf:
            - type: number
              minimum: 0
            - type: string
          title: Employeeshare
          default: '0.00'
        employerShare:
          anyOf:
            - type: number
              minimum: 0
            - type: string
          title: Employershare
          default: '0.00'
      additionalProperties: false
      type: object
      required:
        - name
      title: NonCarBenefits
    payroll__germany__schema__request__Deductions:
      properties:
        name:
          anyOf:
            - $ref: '#/components/schemas/DeductionType'
            - type: 'null'
        amount:
          anyOf:
            - type: number
              minimum: 0
            - type: string
          title: Amount
      additionalProperties: false
      type: object
      required:
        - amount
      title: Deductions
    payroll__germany__schema__request__Reimbursement:
      properties:
        name:
          anyOf:
            - type: string
            - type: 'null'
          title: Name
        amount:
          anyOf:
            - type: number
              minimum: 0
            - type: string
          title: Amount
      additionalProperties: false
      type: object
      required:
        - name
        - amount
      title: Reimbursement
    payroll__germany__schema__response__EmployeeCurrentPayPeriod:
      properties:
        totals:
          $ref: >-
            #/components/schemas/payroll__germany__schema__response__EmployeeTotals
        taxes:
          $ref: >-
            #/components/schemas/payroll__germany__schema__response__EmployeeTaxes
        insurance:
          $ref: >-
            #/components/schemas/payroll__germany__schema__response__EmployeeInsurance
        deductions:
          items:
            $ref: '#/components/schemas/Deduction'
          type: array
          title: Deductions
        reimbursements:
          anyOf:
            - items:
                $ref: '#/components/schemas/Reimbursement-Output'
              type: array
            - type: 'null'
          title: Reimbursements
      additionalProperties: false
      type: object
      title: EmployeeCurrentPayPeriod
    payroll__germany__schema__response__EmployerCurrentPayPeriod:
      properties:
        pensionContribution:
          type: string
          title: Pensioncontribution
          default: '0.00'
        healthInsuranceContribution:
          type: string
          title: Healthinsurancecontribution
          default: '0.00'
        careInsuranceContribution:
          type: string
          title: Careinsurancecontribution
          default: '0.00'
        unemploymentInsuranceContribution:
          type: string
          title: Unemploymentinsurancecontribution
          default: '0.00'
        sickPayInsuranceContribution:
          type: string
          title: Sickpayinsurancecontribution
          default: '0.00'
        maternityPayInsuranceContribution:
          type: string
          title: Maternitypayinsurancecontribution
          default: '0.00'
        insolvencyInsuranceContribution:
          type: string
          title: Insolvencyinsurancecontribution
          default: '0.00'
        flatRateTaxMiniJob:
          type: string
          title: Flatratetaxminijob
          default: '0.00'
        totalBurden:
          type: string
          title: Totalburden
          default: '0.00'
      additionalProperties: false
      type: object
      title: EmployerCurrentPayPeriod
    MiniJobType:
      type: string
      enum:
        - Short Term
        - Earning Limit
      title: MiniJobType
    MiniJobTaxMethod:
      type: string
      enum:
        - Flat Rate
        - Individual
      title: MiniJobTaxMethod
    DeductionType:
      type: string
      enum:
        - Garnishment
        - Loan Repayment
      title: DeductionType
    payroll__germany__schema__response__EmployeeTotals:
      properties:
        totalGrossWages:
          type: string
          title: Totalgrosswages
          default: '0.00'
        taxableGrossWages:
          type: string
          title: Taxablegrosswages
          default: '0.00'
        netWages:
          type: string
          title: Netwages
          default: '0.00'
        totalDeductions:
          type: string
          title: Totaldeductions
          default: '0.00'
        totalReimbursements:
          type: string
          title: Totalreimbursements
          default: '0.00'
        netPay:
          type: string
          title: Netpay
          default: '0.00'
      additionalProperties: false
      type: object
      title: EmployeeTotals
    payroll__germany__schema__response__EmployeeTaxes:
      properties:
        incomeTaxAssessmentBase:
          type: string
          title: Incometaxassessmentbase
          default: '0.00'
        solidarityTaxAssessmentBase:
          type: string
          title: Solidaritytaxassessmentbase
          default: '0.00'
        incomeTax:
          type: string
          title: Incometax
          default: '0.00'
        churchTax:
          type: string
          title: Churchtax
          default: '0.00'
        solidarityTax:
          type: string
          title: Solidaritytax
          default: '0.00'
        totalTax:
          type: string
          title: Totaltax
          default: '0.00'
      additionalProperties: false
      type: object
      title: EmployeeTaxes
    payroll__germany__schema__response__EmployeeInsurance:
      properties:
        insuranceAssessmentBase:
          type: string
          title: Insuranceassessmentbase
          default: '0.00'
        pensionAssessmentBase:
          type: string
          title: Pensionassessmentbase
          default: '0.00'
        healthInsuranceAdditionalRate:
          type: string
          title: Healthinsuranceadditionalrate
          default: '0.00'
        pensionInsurance:
          type: string
          title: Pensioninsurance
          default: '0.00'
        unemploymentInsurance:
          type: string
          title: Unemploymentinsurance
          default: '0.00'
        healthInsurance:
          type: string
          title: Healthinsurance
          default: '0.00'
        careInsurance:
          type: string
          title: Careinsurance
          default: '0.00'
        totalInsurance:
          type: string
          title: Totalinsurance
          default: '0.00'
      additionalProperties: false
      type: object
      title: EmployeeInsurance
    Deduction:
      properties:
        name:
          anyOf:
            - type: string
            - type: 'null'
          title: Name
        amount:
          type: string
          title: Amount
          default: '0.00'
      additionalProperties: false
      type: object
      title: Deduction
    Reimbursement-Output:
      properties:
        name:
          anyOf:
            - type: string
            - type: 'null'
          title: Name
        amount:
          type: string
          title: Amount
          default: '0.00'
      additionalProperties: false
      type: object
      title: Reimbursement
  securitySchemes:
    BearerToken:
      type: http
      scheme: bearer

````