Knowledge base YouServe API's

  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   *For employees with a large amount of versions that cannot be stored, the solution is to remove the older versions until it fits in the storage structure.

  Swagger documentation The following swagger page gives an overview of the endpoints: Payroll API   Endpoints Employees Full load or initial load To get the list of employee basic data of a tenant, the endpoint can be used without any additional parameters. GET https://api.youserve.nl/payroll/v1.0/employees   Incremental load To get the list of employee basic data of a tenant after a specific time, the changedAfter parameter should be included. Also it is possible to include the changedUntil parameter. GET https://api.youserve.nl/payroll/v1.0/employees?changedAfter=2020-05-19   Get employee by Id It is also possible to retrieve the data of a specific employee. GET https://api.youserve.nl/payroll/v1.0/employees/13161246   Employee benefits Full load or initial load To get the list of employee benefits of a tenant, the endpoint can be used without any additional parameters. GET https://api.youserve.nl/payroll/v1.0/employeeBenefits   Incremental load To get the list of employee benefits of a tenant after a specific time, the changedAfter parameter should be included. GET https://api.youserve.nl/payroll/v1.0/employeeBenefits?changedAfter=2020-05-19   Employee fixed payments Full load or initial load To get the list of employee fixed payments of a tenant, the endpoint can be used without any additional parameters. GET https://api.youserve.nl/payroll/v1.0/employeeFixedPayments   Incremental load To get the list of employee fixed payments of a tenant after a specific time, the changedAfter parameter should be included: GET https://api.youserve.nl/payroll/v1.0/employeeFixedPayments?changedAfter=2020-05-19   Employee one-off payments Full load or initial load To get the list of employee one off payments of a tenant, the endpoint can be used without any additional parameters. GET https://api.youserve.nl/payroll/v1.0/employeeOneOffPayments   Incremental load To get the list of employee one off payments of a tenant after a specific time, the changedAfter parameter should be included. GET https://api.youserve.nl/payroll/v1.0/employeeOneOffPayments?changedAfter=2020-05-19   File upload POST employees/{employeeId}/paylips Endpoint for uploading a payslip to the Personal File System of Visma Raet. The endpoint returns a  ticketId  . The document will be uploaded using the type of document provided in the request, or setting a type of document by default for that customer. If this document type is not provided, then the default ovSalaris is used. The API will automatically upload the file to the Personal File System. This is an asynchronized process with an automatic retry mechanism in case the file systems is not available. The retry mechanism will try to upload the file in a maximum of 6 hours. After this period the file will be rejected with a message. Also if the file is too big (maximum 4 Mb) or isn’t a PDF file, the upload will be rejected.   GET payslips/{ticketId}/status Endpoint for getting the status of the uploaded file. The endpoint will return the status of the file. After the file is processed successfully the status Complete is returned.   Postman collection and environment As attachment you can find a zip file with the collection and the environment.