Run Payroll

Run Payroll

curl --request POST \
  --url https://sandbox.intermezzo.ai/germany/payroll \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "payCycle": "Year",
  "payrollGroup": [
    {
      "employeeDetails": {
        "employeeId": 123,
        "yearOfBirth": 1937,
        "isMiniJob": false,
        "miniJobDetails": {
          "miniJobType": "Short Term",
          "taxMethod": "Flat Rate",
          "pensionExemption": false,
          "flatRatePaidByEmployee": false,
          "shortTermFlatTaxRate": 20
        },
        "agreedWorkHoursPerWeek": "0"
      },
      "taxAttributes": {
        "taxClass": "1",
        "isFactor": false,
        "factor": 0.5005,
        "childAllowances": "0",
        "isChurchMember": false,
        "taxState": "Berlin"
      },
      "insuranceDetails": {
        "pensionInsuranceType": "Statutory",
        "healthInsuranceType": "Statutory KV",
        "healthInsurerAgencyCode": "<string>",
        "privateInsuranceMonthly": "0",
        "careInsuranceChildren": 0,
        "isMidiJob": false
      },
      "payDetails": {
        "earnings": [
          {
            "earningType": "<string>",
            "amount": 1,
            "earningFrequency": "Month",
            "isLumpsum": false,
            "doGrossup": false
          }
        ],
        "benefits": [
          {
            "name": "<string>",
            "value": 1,
            "additionalPayments": "0.00",
            "privateTrip": "0.00"
          }
        ],
        "deductions": [
          {
            "amount": 1,
            "name": "Garnishment"
          }
        ],
        "reimbursements": [
          {
            "name": "<string>",
            "amount": 1
          }
        ]
      }
    }
  ],
  "payDate": "2023-12-25"
}
'

{
  "payslips": [
    {
      "employeeId": 123,
      "currentPayPeriod": {
        "employee": {
          "totals": {
            "totalGrossWages": "0.00",
            "taxableGrossWages": "0.00",
            "netWages": "0.00",
            "totalDeductions": "0.00",
            "totalReimbursements": "0.00",
            "netPay": "0.00"
          },
          "taxes": {
            "incomeTaxAssessmentBase": "0.00",
            "solidarityTaxAssessmentBase": "0.00",
            "incomeTax": "0.00",
            "churchTax": "0.00",
            "solidarityTax": "0.00",
            "totalTax": "0.00"
          },
          "insurance": {
            "insuranceAssessmentBase": "0.00",
            "pensionAssessmentBase": "0.00",
            "healthInsuranceAdditionalRate": "0.00",
            "pensionInsurance": "0.00",
            "unemploymentInsurance": "0.00",
            "healthInsurance": "0.00",
            "careInsurance": "0.00",
            "totalInsurance": "0.00"
          },
          "deductions": [
            {
              "name": "<string>",
              "amount": "0.00"
            }
          ],
          "reimbursements": [
            {
              "name": "<string>",
              "amount": "0.00"
            }
          ]
        },
        "employer": {
          "pensionContribution": "0.00",
          "healthInsuranceContribution": "0.00",
          "careInsuranceContribution": "0.00",
          "unemploymentInsuranceContribution": "0.00",
          "sickPayInsuranceContribution": "0.00",
          "maternityPayInsuranceContribution": "0.00",
          "insolvencyInsuranceContribution": "0.00",
          "flatRateTaxMiniJob": "0.00",
          "totalBurden": "0.00"
        }
      },
      "paymentPeriod": "Month"
    }
  ],
  "summary": {
    "employer": {
      "pensionContribution": "0.00",
      "healthInsuranceContribution": "0.00",
      "careInsuranceContribution": "0.00",
      "unemploymentInsuranceContribution": "0.00",
      "sickPayInsuranceContribution": "0.00",
      "maternityPayInsuranceContribution": "0.00",
      "insolvencyInsuranceContribution": "0.00",
      "flatRateTaxMiniJob": "0.00",
      "totalBurden": "0.00"
    }
  }
}

POST

germany

payroll

Run Payroll

curl --request POST \
  --url https://sandbox.intermezzo.ai/germany/payroll \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "payCycle": "Year",
  "payrollGroup": [
    {
      "employeeDetails": {
        "employeeId": 123,
        "yearOfBirth": 1937,
        "isMiniJob": false,
        "miniJobDetails": {
          "miniJobType": "Short Term",
          "taxMethod": "Flat Rate",
          "pensionExemption": false,
          "flatRatePaidByEmployee": false,
          "shortTermFlatTaxRate": 20
        },
        "agreedWorkHoursPerWeek": "0"
      },
      "taxAttributes": {
        "taxClass": "1",
        "isFactor": false,
        "factor": 0.5005,
        "childAllowances": "0",
        "isChurchMember": false,
        "taxState": "Berlin"
      },
      "insuranceDetails": {
        "pensionInsuranceType": "Statutory",
        "healthInsuranceType": "Statutory KV",
        "healthInsurerAgencyCode": "<string>",
        "privateInsuranceMonthly": "0",
        "careInsuranceChildren": 0,
        "isMidiJob": false
      },
      "payDetails": {
        "earnings": [
          {
            "earningType": "<string>",
            "amount": 1,
            "earningFrequency": "Month",
            "isLumpsum": false,
            "doGrossup": false
          }
        ],
        "benefits": [
          {
            "name": "<string>",
            "value": 1,
            "additionalPayments": "0.00",
            "privateTrip": "0.00"
          }
        ],
        "deductions": [
          {
            "amount": 1,
            "name": "Garnishment"
          }
        ],
        "reimbursements": [
          {
            "name": "<string>",
            "amount": 1
          }
        ]
      }
    }
  ],
  "payDate": "2023-12-25"
}
'

{
  "payslips": [
    {
      "employeeId": 123,
      "currentPayPeriod": {
        "employee": {
          "totals": {
            "totalGrossWages": "0.00",
            "taxableGrossWages": "0.00",
            "netWages": "0.00",
            "totalDeductions": "0.00",
            "totalReimbursements": "0.00",
            "netPay": "0.00"
          },
          "taxes": {
            "incomeTaxAssessmentBase": "0.00",
            "solidarityTaxAssessmentBase": "0.00",
            "incomeTax": "0.00",
            "churchTax": "0.00",
            "solidarityTax": "0.00",
            "totalTax": "0.00"
          },
          "insurance": {
            "insuranceAssessmentBase": "0.00",
            "pensionAssessmentBase": "0.00",
            "healthInsuranceAdditionalRate": "0.00",
            "pensionInsurance": "0.00",
            "unemploymentInsurance": "0.00",
            "healthInsurance": "0.00",
            "careInsurance": "0.00",
            "totalInsurance": "0.00"
          },
          "deductions": [
            {
              "name": "<string>",
              "amount": "0.00"
            }
          ],
          "reimbursements": [
            {
              "name": "<string>",
              "amount": "0.00"
            }
          ]
        },
        "employer": {
          "pensionContribution": "0.00",
          "healthInsuranceContribution": "0.00",
          "careInsuranceContribution": "0.00",
          "unemploymentInsuranceContribution": "0.00",
          "sickPayInsuranceContribution": "0.00",
          "maternityPayInsuranceContribution": "0.00",
          "insolvencyInsuranceContribution": "0.00",
          "flatRateTaxMiniJob": "0.00",
          "totalBurden": "0.00"
        }
      },
      "paymentPeriod": "Month"
    }
  ],
  "summary": {
    "employer": {
      "pensionContribution": "0.00",
      "healthInsuranceContribution": "0.00",
      "careInsuranceContribution": "0.00",
      "unemploymentInsuranceContribution": "0.00",
      "sickPayInsuranceContribution": "0.00",
      "maternityPayInsuranceContribution": "0.00",
      "insolvencyInsuranceContribution": "0.00",
      "flatRateTaxMiniJob": "0.00",
      "totalBurden": "0.00"
    }
  }
}

Authorizations

Authorization

string

header

required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Body

application/json

Input parameters according to PAP2025

payCycle

enum<string>

required

Lohnzahlungszeitraum (LZZ)

Available options:

Year,

Month,

Week,

Day

payrollGroup

PayrollRequestBase · object[]

required

Show child attributes

payrollGroup.employeeDetails

EmployeeDetails · object

required

Show child attributes

payrollGroup.employeeDetails.employeeId

integer

required

Mitarbeiterkennzeichen - Employee identification number

payrollGroup.employeeDetails.yearOfBirth

integer

required

Geburtsjahr - Birth Year to check eligibility for Altersentlastungsbetrag

Required range: 1850 <= x <= 2025

payrollGroup.employeeDetails.isMiniJob

boolean

default:false

Whether the employee is a mini-jobber

payrollGroup.employeeDetails.miniJobDetails

MiniJobDetails · object

Mini-job specific details (required when is_mini_job is True)

Show child attributes

payrollGroup.employeeDetails.miniJobDetails.miniJobType

enum<string>

required

Type of mini-job: short-term or earning-limit based

Available options:

Short Term,

Earning Limit

payrollGroup.employeeDetails.miniJobDetails.taxMethod

enum<string>

required

Tax method for mini-jobs: flat rate or individual taxation

Available options:

Flat Rate,

Individual

payrollGroup.employeeDetails.miniJobDetails.pensionExemption

boolean

default:false

Whether the mini-jobber is exempt from pension insurance

payrollGroup.employeeDetails.miniJobDetails.flatRatePaidByEmployee

boolean

default:false

Whether the 2% flat rate tax is paid by the employee instead of the employer

payrollGroup.employeeDetails.miniJobDetails.shortTermFlatTaxRate

enum<integer> | null

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

Available options:

20,

25

payrollGroup.employeeDetails.agreedWorkHoursPerWeek

default:0

Agreed work hours per week

Required range: x >= 0

payrollGroup.taxAttributes

TaxAttributes · object

required

Show child attributes

payrollGroup.taxAttributes.taxClass

enum<string>

required

Steuerklasse (STKL) - Tax class

Available options:

1,

2,

3,

4,

5,

6

payrollGroup.taxAttributes.isFactor

boolean | null

default:false

Faktorverfahren (AF) - Factor procedure flag (only for tax class IV)

payrollGroup.taxAttributes.factor

Faktor (F) - Factor for factor procedure

Required range: 0.001 <= x < 1Must be a multiple of 0.001

payrollGroup.taxAttributes.childAllowances

default:0

Kinderfreibeträge (ZKF) - Number of child allowances (decimal place for shared allowances)

Required range: 0 <= x <= 9Must be a multiple of 0.5

payrollGroup.taxAttributes.isChurchMember

boolean

default:false

Religionsgemeinschaft (R) - Church membership

payrollGroup.taxAttributes.taxState

enum<string> | null

default:Berlin

Bundesländer - Residency state

Available options:

Baden-Württemberg,

Bayern,

Berlin,

Brandenburg,

Bremen,

Hamburg,

Hessen,

Mecklenburg-Vorpommern,

Niedersachsen,

Nordrhein-Westfalen,

Rheinland-Pfalz,

Saarland,

Sachsen,

Sachsen-Anhalt,

Schleswig-Holstein,

Thüringen

payrollGroup.insuranceDetails

InsuranceDetails · object

required

Show child attributes

payrollGroup.insuranceDetails.pensionInsuranceType

enum<string>

required

Rentenversicherung (KRV) - Pension insurance type

Available options:

Statutory,

Other

payrollGroup.insuranceDetails.healthInsuranceType

enum<string>

required

Krankenversicherung (PKV) - Health insurance type

Available options:

Statutory KV,

Private KV without employer subsidy,

Private KV with employer subsidy

payrollGroup.insuranceDetails.healthInsurerAgencyCode

string | null

Krankenversicherungscode (KVK) - Health insurer agency code

payrollGroup.insuranceDetails.privateInsuranceMonthly

default:0

Private Krankenversicherung (PKPV) - Monthly private health/care insurance contribution

Required range: x >= 0

payrollGroup.insuranceDetails.careInsuranceChildren

integer

default:0

Anzahl Kinder Pflegeversicherung (PVA) - Number of children for care insurance discount (0-5), choose 5 for 5 or more

Required range: 0 <= x <= 5

payrollGroup.insuranceDetails.isMidiJob

boolean

default:false

Whether the employee is a midi-jobber

payrollGroup.payDetails

Gross · object

required

Show child attributes

payrollGroup.payDetails.earnings

(SalariedEarnings · object | HourlyEarnings · object | OtherEarnings · object)[] | null

required

SalariedEarnings
HourlyEarnings
OtherEarnings

Show child attributes

payrollGroup.payDetails.earnings.earningType

string

required

Allowed value: "Salary"

payrollGroup.payDetails.earnings.amount

required

Earnings amount (taxable gross)

Required range: x >= 0

payrollGroup.payDetails.earnings.earningFrequency

enum<string> | null

default:Month

If recurring, specify the frequency

Available options:

Year,

Month,

Week,

Day

payrollGroup.payDetails.earnings.isLumpsum

boolean | null

default:false

True if onetime (Einmalig). False if recurring (Laufend)

payrollGroup.payDetails.earnings.doGrossup

boolean | null

default:false

True if the amount needs to be grossed up

payrollGroup.payDetails.benefits

(Car · object | NonCarBenefits · object)[] | null

required

Car
NonCarBenefits

Show child attributes

payrollGroup.payDetails.benefits.name

string

required

Allowed value: "Company Car"

payrollGroup.payDetails.benefits.value

Cost of car

Required range: x >= 0

payrollGroup.payDetails.benefits.additionalPayments

default:0.00

Zuzahl. Firmenw. stpfl.

payrollGroup.payDetails.benefits.privateTrip

default:0.00

Privatfahrten

Required range: x >= 0

payrollGroup.payDetails.deductions

Deductions · object[] | null

Show child attributes

payrollGroup.payDetails.deductions.amount

required

Required range: x >= 0

payrollGroup.payDetails.deductions.name

enum<string> | null

Available options:

Garnishment,

Loan Repayment

payrollGroup.payDetails.reimbursements

Reimbursement · object[] | null

Show child attributes

payrollGroup.payDetails.reimbursements.name

string | null

required

payrollGroup.payDetails.reimbursements.amount

required

Required range: x >= 0

payDate

string<date>

Payment Date for this payroll

Response

Successful Response

payslips

Payslip · object[]

required

Show child attributes

payslips.employeeId

integer

required

payslips.currentPayPeriod

CurrentPayPeriod · object

required

Show child attributes

payslips.currentPayPeriod.employee

EmployeeCurrentPayPeriod · object

Show child attributes

payslips.currentPayPeriod.employee.totals

EmployeeTotals · object

Show child attributes

payslips.currentPayPeriod.employee.totals.totalGrossWages

string

default:0.00

payslips.currentPayPeriod.employee.totals.taxableGrossWages

string

default:0.00

payslips.currentPayPeriod.employee.totals.netWages

string

default:0.00

payslips.currentPayPeriod.employee.totals.totalDeductions

string

default:0.00

payslips.currentPayPeriod.employee.totals.totalReimbursements

string

default:0.00

payslips.currentPayPeriod.employee.totals.netPay

string

default:0.00

payslips.currentPayPeriod.employee.taxes

EmployeeTaxes · object

Show child attributes

payslips.currentPayPeriod.employee.taxes.incomeTaxAssessmentBase

string

default:0.00

payslips.currentPayPeriod.employee.taxes.solidarityTaxAssessmentBase

string

default:0.00

payslips.currentPayPeriod.employee.taxes.incomeTax

string

default:0.00

payslips.currentPayPeriod.employee.taxes.churchTax

string

default:0.00

payslips.currentPayPeriod.employee.taxes.solidarityTax

string

default:0.00

payslips.currentPayPeriod.employee.taxes.totalTax

string

default:0.00

payslips.currentPayPeriod.employee.insurance

EmployeeInsurance · object

Show child attributes

payslips.currentPayPeriod.employee.insurance.insuranceAssessmentBase

string

default:0.00

payslips.currentPayPeriod.employee.insurance.pensionAssessmentBase

string

default:0.00

payslips.currentPayPeriod.employee.insurance.healthInsuranceAdditionalRate

string

default:0.00

payslips.currentPayPeriod.employee.insurance.pensionInsurance

string

default:0.00

payslips.currentPayPeriod.employee.insurance.unemploymentInsurance

string

default:0.00

payslips.currentPayPeriod.employee.insurance.healthInsurance

string

default:0.00

payslips.currentPayPeriod.employee.insurance.careInsurance

string

default:0.00

payslips.currentPayPeriod.employee.insurance.totalInsurance

string

default:0.00

payslips.currentPayPeriod.employee.deductions

Deduction · object[]

Show child attributes

payslips.currentPayPeriod.employee.deductions.name

string | null

payslips.currentPayPeriod.employee.deductions.amount

string

default:0.00

payslips.currentPayPeriod.employee.reimbursements

Reimbursement · object[] | null

Show child attributes

payslips.currentPayPeriod.employee.reimbursements.name

string | null

payslips.currentPayPeriod.employee.reimbursements.amount

string

default:0.00

payslips.currentPayPeriod.employer

EmployerCurrentPayPeriod · object

Show child attributes

payslips.currentPayPeriod.employer.pensionContribution

string

default:0.00

payslips.currentPayPeriod.employer.healthInsuranceContribution

string

default:0.00

payslips.currentPayPeriod.employer.careInsuranceContribution

string

default:0.00

payslips.currentPayPeriod.employer.unemploymentInsuranceContribution

string

default:0.00

payslips.currentPayPeriod.employer.sickPayInsuranceContribution

string

default:0.00

payslips.currentPayPeriod.employer.maternityPayInsuranceContribution

string

default:0.00

payslips.currentPayPeriod.employer.insolvencyInsuranceContribution

string

default:0.00

payslips.currentPayPeriod.employer.flatRateTaxMiniJob

string

default:0.00

payslips.currentPayPeriod.employer.totalBurden

string

default:0.00

payslips.paymentPeriod

enum<string>

default:Month

Lohnzahlungszeitraum (LZZ)

Available options:

Year,

Month,

Week,

Day

summary

Summary · object

Show child attributes

summary.employer

EmployerSummary · object

Show child attributes

summary.employer.pensionContribution

string

default:0.00

summary.employer.healthInsuranceContribution

string

default:0.00

summary.employer.careInsuranceContribution

string

default:0.00

summary.employer.unemploymentInsuranceContribution

string

default:0.00

summary.employer.sickPayInsuranceContribution

string

default:0.00

summary.employer.maternityPayInsuranceContribution

string

default:0.00

summary.employer.insolvencyInsuranceContribution

string

default:0.00

summary.employer.flatRateTaxMiniJob

string

default:0.00

summary.employer.totalBurden

string

default:0.00

List Health Agencies

Approve Payroll

⌘I

Core

Germany

Great Britain

Authorizations

Body

Response