Payroll API - Domain model and concepts

[#1]

• Employee basic data
• Employee benefits
• Employee fixed payments
• Employee one-off payments
• Extensions fields for German companies
• Extensions fields for Belgian companies

This API is intended for external payroll systems and allows them to fetch the necessary data they need to run the payrolls.

Employee basic data

Property	Description	Example	Data type
isDeleted	If the employee was removed in the core system	true	boolean
customerId	The code of the tenant	4024898	string
companyId	The id of the company	15951	string
upi	The unique id assigned to the employee	32789	string
employeeCode	The code of the employee	1079224	string
employeeId	The employee id in the core system	13665966	string
contractId	The contract id in the core system	13665965	string
hireDate	The hire date of the contract	2017-03-01T00:00:00	DateTime
dischargeDate	The discharge date of the contract	2020-12-30T00:00:00	DateTime
personData	List of person data versions (*)
	validFromDate	2017-03-01T00:00:00	DateTime
	validToDate	2020-12-30T00:00:00	DateTime
	personalDetails (name, lastname, birthdate, prefix...)
	addresses (list of addresses (home and postal))
	contactInformation (personal email, work email, work number...)
	extensions
lastNameAtBirth	The last name at birth of the employee. Also known as the family name	Vries	string
prefixLastNameAtBirth	The prefix of the employee's last name at birth	de	string
lastNameToUse	The last name used by the employee at present	Vries - Van Eijck	string
prefixLastNameToUse	The prefix of last name used by the employee at present	Van	String
initials	The initials of the employee	A.B.	string
firstNames	The official given names of the employee	Amy Beatrice	string
knownAs	The name which is used by the employee as first name	Amy	string
titlePrefix	The title prefix of the employee	Mr.	string
titleSuffix	The title suffix of the employee	Jr.	string
gender	Gender of the employee	Female	string
dateOfBirth	The date of birth of the employee	1970-01-01	DateTime
dateDeceased	The date of the death	2020-01-01	DateTime?
countryOfBirth	The country of birth of the employee	ES	string
placeOfBirth	The place of birth of the employee	Amsterdam	string
maritalStatus	The marital status of the employee	1	string (reference list)
primaryNationality	The primary nationality of the employee	0001	string (reference list)
nationalIdentificationNumber	The national identification number of the employee	367565572	string
addresses	List of addresses		array of objects
	type	Home	string
	street	Kerkstraat	string
	houseNumber	1	string
	addition	C	string
	additionalInfo	2nd floor	string
	zipCode	1234 AB	string
	city	Amersfoort	string
	region	Region	string
	country	NL	string (reference list)
contactInformation	emailAddresses
	phoneNumbers
emailAddresses	List of email addresses
	type	Private	string
	address	p.user@example.com	string
phoneNumbers	List of phone numbers
	type	Home	string
	number	+3188 123 45 67	string
extensions	List of custom fields
	key	AmountOfChildren	string
	value	3	string
employmentData	List of employment versions (*)
	validFromDate	2017-03-01T00:00:00	DateTime
	validToDate	2020-12-30T00:00:00	DateTime
	contractDetails
	costAllocations
	bankAccounts
	workAmountPattern
	extensions
contractNumber	The contract number	1	string
firstHireDate	The first hire date or original hire date of an employee within the organization.	2017-03-01T00:00:00	DateTime
location	The location of where the employment is being performed	Headquarter	string
contractType	The type of the contract		string
employmentType	Code of the employment type	4	string (reference list)
daysPeriod	Working days in a period for the employee	5	decimal
classification	Classification	110001	string (reference list)
jobProfile	The job profile code	DEV	string (reference list)
collectiveLaborAgreement	The collective labor agreement of the company	13124836	string (reference list)
organizationalUnit	The organizational unit of the employee	31081923	string (reference list)
terminationReason	The reason of the termination of the contract	REA	string (reference list)
costAllocations	List of cost allocations
	costCenter	cc1	string
	percentage	100	int
bankAccounts	List of bank accounts
	country	NL	string (reference list)
	iban	NL62INGB1954254121	string
	accountOwner		string
	bic	ABNANL2AALC	string
	routingNumber		string
	accountNumber	1954254121	string
	bankName		string
	bankAccountType	01	string (reference list)
	currency	EUR	string (by default is EUR)
workAmountPattern	workingAmount	40	decimal
	workingUnit	Hours	string
	workingPeriod	1	string (reference list)
	workPatternId	40HoursWeek	string
	workingPatterns (list of work pattern versions that applies to the period of the contract version)
workingPattern	validFromDate	2017-03-01T00:00:00	DateTime
	validToDate	2020-12-30T00:00:00	DateTime
	days (list of workingDay)
workingDay	dayIndexNumber	1	int
	dayOfWeek	Monday = 1	enum
	hours	8	decimal
Dependents	List of dependents dependentId dependentPersonNumber dependentData: List of dependent versions
dependentId	Identifier of the dependent	1	int
dependentPersonNumber	Person number of the dependent	10001	string
dependentData	List of dependent versions
	prefix	Van	string
	lastName	Vries	string
	firstName	Erika	string
	gender	Female	string
	dateOfBirth	2001-01-01	DateTime
	dateOfDeath		DateTime
	relationship	Partner	string
	relationshipStartDate	2020-01-01	DateTime
	relationshipEndDate	2020-12-31	DateTime
	validFromDate	2020-01-01	DateTime
	validToDate	9999-12-31	DateTime
	extensions: List of custom fields per dependent and country

(*) The list of versions of PersonData and ContractData includes all versions, when the employee is in service and out of service.

The extensions fields in PersonData, EmploymentData and DependentData would be filled in with custom fields.

No dependent data is available for German employees.

Employee benefits

Property	Description	Example	Data type
IsDeleted	If the employee was removed in the core system	true	boolean
customerId	The code of the tenant	4024898	string
employeeCode	The code of the employee	1079224	string
employeeId	The employee id in the core system	13665966	string
contractId	The contract id in the core system	13665965	string
Benefits	List of benefits of the employee
	PayComponent	HourlySalary	string
	value	20	string
	validFrom	2017-03-01T00:00:00	DateTime
	validTo	2020-12-30T00:00:00	DateTime

Pay components included as Benefits:

Pay component	Element number
KpiCompensation	10201240
PersonalAllowanceB	10201251
PersonalAllowanceC	10201252
PersonalAllowanceReduction	10201253
PersonalAllowanceIncludingCao	10201254
SightingFee	10201255
JobBonus	10201256
StandBy	10201257
CarAllowance	10201258
CostReimbursementTax	10201259
TravelExpenses	10204902
DivergentSalary	10300579
PersonalAllowancePercentage	10303254
HourlySalary	10518747
SalaryAmount	10302976
SalaryScale	10300574
SalaryLevel	10300575
CategorieSalaryScale	10300576

Employee fixed payments

Property	Description	Example	Data type
IsDeleted	If the employee was removed in the core system	true	boolean
customerId	The code of the tenant	4024898	string
employeeCode	The code of the employee	1079224	string
employeeId	The employee id in the core system	13665966	string
contractId	The contract id in the core system	13665965	string
FixedPayments	List of fixed payments of the employee
	PayComponent	Fixed allowance	string
	value	10	string
	validFrom	2017-03-01T00:00:00	DateTime
	validTo	2020-12-30T00:00:00	DateTime

Pay components included as Fixed payments:

Pay component	Element number
GrossFixedFee	10207320
InternshipCompensationNB	10207480
StaffBonus	10203907
ExpenseAllowanceUntaxed	10202687
BAdditionTaxableIncomeFixed	10207160

Employee one-off payments

Property	Description	Example	Data type
IsDeleted	If the employee was removed in the core system	true	boolean
customerId	The code of the tenant	4024898	string
employeeCode	The code of the employee	1079224	string
employeeId	The employee id in the core system	13665966	string
contractId	The contract id in the core system	13665965	string
OneOffPayments	List of one off payments of the employee
	PayComponent	Train ticket	string
	value	17	string
	date	2017-03-01T00:00:00	DateTime

Pay components included as One Off Payments:

Pay component	Element number
DailyAllowenceNet01	10206880
DailyAllowenceNet02	10206882
DailyAllowenceNet03	10206884
DailyAllowenceNet04	10206886
DailyAllowenceNet05	10206888
DailyAllowenceNet06	10206890
DailyAllowenceNet07	10206892
DailyAllowenceNet09	10206896
DailyAllowenceNet10	10206898
DailyAllowenceNet11	10206900
DailyAllowenceNet12	10206902
DailyAllowenceNet13	10206904
KilometresStatement	10204904
CAllowenceVar	10200763
AAllowenceVar	10200759

Extensions fields for German companies

Person data extensions

Property	Example	Data type
SocialSecurityNumber	15090270W758	string
TaxIdentificationNumber	1234562001	string

Employment data extensions

Property	Example	Data type
CapitalAccumulationBenefits	2	string (reference list)
CertificationOfIncreasedPensionInsurance	2	string (reference list)
CertificationOfParenthood	2	string (reference list)
CertificationOfPensionInsuranceExemption	2	string (reference list)
ChildDaycareAllowance	2	string (reference list)
ChildTaxCredit	1	string (reference list)
CompanyCar	1	string (reference list)
CrossborderWorker	5	string (reference list)
DegreeOfDisability	9	string (reference list)
EducationDegree	1	string (reference list)
EmployeeGroup	1	string (reference list)
EmployerFundedPension	1	string (reference list)
HealthInsuranceType	3	string (reference list)
LevelOfEducation	9	string (reference list)
LimitedincomeTax	2	string (reference list)
MainEmploymentAtOtherEmployer	2	string (reference list)
Name	Audi BKK	string
Place	Ingolstadt	string
Religion	10	string (reference list)
TaxGroup	1	string (reference list)
TravelAllowance	1	string (reference list)
Vouchers	2	string (reference list)
With	3	string (reference list)
WorkingAs	71394-3	string (reference list)
WorkingLocation	HH	string (reference list)
ContractType	1	string (reference list)

Extensions fields for Belgian companies

Employment data extensions

Property	Description	Example	Data type	Element number in HRCB
LinkingTableBICCodeBelgium	Linking table bic code	2	string (reference list)	10525244
StartDateLimosaNotification	Effective date Limosa notification	2020-01-01	DateTime	10525245
NationalInsuranceNumberOld	National Insurance number (old)	750915 4998 658	string	10525231
LanguagePayslip	Salary slip language	1	string (reference list)	10525253
Flex	Flex	1	boolean	10525255
IncomePartner	Income of the partner	2	string (reference list)	10525252
CountryOfBirth	Country of birth	2	string (reference list)	10517302
EndDateLimosaNotification	End of limosa notification	2021-01-01	DateTime	10525246
NationalInsuranceNumber	INSZ number	750915 4998 659	string	10517301
DegreeOfEducation	Education degree	2	string (reference list)	10525254
MaritalStatusBE	Marital status	2	string (reference list)	10517075
TaxCivilStatusOnEmployment	Fiscal Marital status upon employment	1	string (reference list)	10519436
PrintPaySlips	Print payslips	1	boolean	7707
CategoryEmployee	Category of the employee	A	string (reference list)	10525264
ReasonForDismissal	Reason for dismissal	BP	string (reference list)	10525248
SeniorityDate	Seniority date	2020/08/14	DateTime	10525233
HierarchicalStatute	Hierarchical status	1	string (reference list)	10520266
TaxStatus	Tax status	1	string (reference list)	10525251
StartDateParentalLeave	Start date interruption parental leave	2021/01/01	DateTime	10525234
EndDateParentalLeave	End date interruption parental leave	2021/03/01	DateTime	10525235
ParentalLeave	Type interruption parental leave	OH	string (reference list)	10525257
PercentageInterruptionParentalLeave	Percentage interruption parental leave	12,00	number	10525237
StartDatePalliativeLeave	Start date interruption palliative leave	2021/01/01	DateTime	10525238
EndDatePalliativeLeave	End date interruption palliative leave	2021/03/01	DateTime	10525239
PalliativeLeave	Type interruption palliative leave	PD	string (reference list)	10525258
PercentagePalliativeLeave	Percentage interruption palliative leave	13,00	number	10525240
StartDateMedicalAssistance	Star date interruption medical assistance	2021/01/03	DateTime	10525241
EndDateMedicalAssistance	End date interruption medical assistance	2021/01/04	DateTime	10525242
MedicalAssistance	Type interruption medical assistance	MV	string (reference list)	10525259
PercentageMedicalAssistance	Percentage interruption medical assistance	14,00	number	10525243
StartDateTimeCredit	Start date interruption time credit	2021/01/05	DateTime	10525261
EndDateTimeCredit	End date interruption time credit	2021/01/06	DateTime	10525262
TimeCredit	Type interruption time credit	TV	string (reference list)	10525260
PercentageTimeCredit	Percentage interruption time credit	15,00	number	10525263
Contract1Type	Type of contract 1	1	string (reference list)	10525766
Contract2Type	Type of contract 2	2	string (reference list)	10525767
Contract3Type	Type of contract 3	3	string (reference list)	10525776
Contract1StartDate	Start date of contract 1	01/01/2021 00:00:00	DateTime	10525770
Contract2StartDate	Start date of contract 2	02/01/2021 00:00:00	DateTime	10525774
Contract3StartDate	Start date of contract 3	03/01/2021 00:00:00	DateTime	10525775
Contract1EndDate	End date of contract 1	01/31/2021 00:00:00	DateTime	10525771
Contract2EndDate	End date of contract 2	02/28/2021 00:00:00	DateTime	10525772
Contract3EndDate	End date of contract 3	03/31/2021 00:00:00	DateTime	10525773
NumberOfDependentChildren	Number of dependent children for tax purposes	1	int	10517103
NumberOfDependentHandicappedChildren	Number of disabled dependent children	1	int	10517104
PartnerIncome	Professional income partner	2	string (reference list)	10517076
HandicappedPartner	Disabled partner	1	boolean	10517102
HospitalizationInsuranceForPartner	Hospitalization insurance for partner	1	boolean	10526113
NumberOfDependentPersons	Number of other dependent residents <65 years	1	int	10517105
NumberOfDependentDependent	Number of other disabled residents dependent	1	int	10517106
NumberOfDependentPersonsGt65	Number of other dependents >= 65 years	1	int	10517107
NumberOfDependentHandicappePersonsGt65	Number of disabled residents dependent> 65 years	1	int	10517108
TaxRegimeBE	Belasting regime [BE]			10528135
SocialSecurityReductionReasonBE	Reden verlaging Sociale zekerheid [BE]			10528136
TaxReductionReasonBE	Reden belasting verlaging [BE]			10528137
SocialSecurityRegimeBE	Sociaal zekerheid regime [BE]			10528138
PartimeIndicationBE	Deeltijd indicatie [BE]			10528139
WorkScheduleNumberBE	Werkschema nummer  [BE]			10528141
PaymentMethodBE	Betaalwijze [BE]			10528223
EmployeeContractBE	Arbeidsovereenkomst [BE]			10528224
GroupNumberBE	Groepsnummer [BE]			10528225
DentalInsurancePlus18BE	Dentalverzekering +18 [BE]			10528226
DentalInsuranceMinus18BE	Dentalverzekering -18 [BE]			10528227
NationalRegisterNumberProTimeBE	INSZ-nummer ProTime [BE]			10528228
EMailProTimeBE	E-mail ProTime [BE]			10528229
PartnerProfessioneBE	Beroep echtgenote [BE]			10528231
PeopleDependentOn65InformalCareBE	Personen ten laste 65+ mantelzorg [BE]			10528239
PersonsAtChargeDisabledPartnerBE	Pers. ten laste: Mindervalide echtgenote [BE]			10528240
PersonsAtChargePartnerBE	Personen ten laste-echtgenote [BE]			10528241
HigherValueMealVouchersBE	Hogere waarde maaltijdcheques [BE]			10528242
MonthlyGrossIncomeScaleBE	Barema brutoloon  [BE]			10528243
HourlyWageScaleBE	Barema uurloon (chauffeurs) [BE]			10528244
SalaryLevelBE	Looncategorie [BE]			10528245
HourlyWageBE	Basis uurloon arbeiders [BE]			10528246
MonthlyGrossIncomeBE	Maandloon bedienden [BE]			10528247
AlternativeHourlyWage2BE	Basis uurloon chauffeurs  [BE]			10528248
ReasonWageIncreaseBE!!	Reden loonsverhoging [BE]			10528249
ExtraAllowance1BE	Distributiepremie chauffeurs [BE]			10528250
ExtraAllowance2BE	Toeslag trainer chauffeurs [BE]			10528251
WorkSchemeCodeBE	Werkschema code [BE]			10528252
DisabledEmployee	Minder valide medewerker			10528253
TypeOfPayslipBE	Type loonstrook [BE]			10528254
Regime5Or6BE	Stelsel 5-6 [BE]			10528259
BirthcountryBE	Geboorteland [BE]			10528257
Nationality	Nationaliteit			10519287
CountryBE	Woonland [BE]			10528256
FunctionLevelBE	Functieniveau [BE]			10528456
DepartureReasonBE	Reden ontslag [BE]			10528258
HospitalisationInsurancep18	Hospitalisatieverzekering +18 [BE]			10528431
HospitalisationInsurancem18	Hospitalisatieverzekering -18 [BE]			10528432
WorkLocation	Work Location			7449
LastNameToUse	Last name to use			590
NumberOfPeopleDependentOn65PlusInformCare	Number of people dependent 65+ on  informal care			10528515

Dependent data extensions

Property	Description	Example	Data type	Element number in HRCB
DependentPersonStatus	Status	1	string (reference list)	10519335
DependentPersonIsDisabled	Disabled	1	boolean	10519251
HospitalizationInsuranceForChild	Hospitalization insurance for a child?	1	boolean	10526114
DisabilityRate	Disability rate	50	decimal	10526116
IsChildBenefitReceived	Are child benefits received?	1	boolean	10526115