Knowledge base YouServe API's

  This API is intended for external HR solutions and other external consumers in order to create and update data in HR Core and Payroll. This is an entity driven API, based on the following entities: Employee: Person that belongs to a company Contract: Employee in a specific position Payroll data: Benefits, fixed payments and one off payment of an employee Value lists     Employee De beschikbare velden voor dit end-point zijn terug te vinden in de bijlage "HR Core and Payroll API - Domain model and concepts.xlsx"   Contract De beschikbare velden voor dit end-point zijn terug te vinden in de bijlage "HR Core and Payroll API - Domain model and concepts.xlsx"   Salary Scale De beschikbare velden voor dit end-point zijn terug te vinden in de bijlage "HR Core and Payroll API - Domain model and concepts.xlsx"   Value lists and other entities Company Collective Labor Agreement Element Number Label Description 47 Code Code 65 WorkSchedule Work Schedule 191 ClientCLA Client CLA 194 NameCLAImplementationCompany Name CLA Implementation Company 549 Name Name 565 WorkHoursScheduleWeek1 Work Hours Schedule Week 1 587 FlexBundleIdentification Flex Bundle Identification 893 EmployerCategory Employer Category 10520175 SequenceNumberCompanyCLA Sequence Number Company CLA 18 CompanyCode Company Code Organizational Unit Element Number Label Description 548 Code Code 549 Name Name 7011 BackupManager Backup Manager 7012 NumberOfFTEs Number Of FTEs 7137 Manager Manager 7271 NumberKvK Number KvK 7475 OrganizationType Organization Type 7476 NumberOfEmployees Number Of Employees 7477 YearEstimation Year Estimation 7478 EducationBudget Education Budget Establishment Unit Element Number Label Description 147 StreetHouseNumber Street House Number 548 Code Code 7271 NumberKvK Number KvK 7375 FaxNumber Fax Number 7380 HouseNumberMailingAddress House Number Mailing Address 7381 MunicipalityMailingAddress Municipality Mailing Address 7382 PostalCodeMailingAddress Postal Code Mailing Address 7383 StreetMailingAddress Street Mailing Address 7384 HouseNumberSuffixMailingAddress House Number Suffix Mailing Address 7415 TelephoneNumber Telephone Number 7445 WorklocationName Worklocation Name 7446 Location Location 7447 EmailAddress Email Address 7451 HouseNumber House Number 7452 HouseNumberSuffix House Number Suffix 7453 PostCode PostCode 7454 Street Street 7456 Website Website 7571 CountryMailingAddress Country Mailing Address 8099 LocationDescription Location Description 8100 LocationDescriptionMailingAddress Location Description Mailing Address 8101 RegionNameAbroadMailingAddress Region Name Abroad Mailing Address 8110 Country Country 10205283 NameRegionAbroad Name Region Abroad   Values lists Employee MaritalStatus - 37  Gender - 36 Nationality - 10204761 Communication Language - 10 34 Home Address - 7571 Postal Address - Country AccountType1-10 (10000085,10000086,10000087,10000088,10000089,10000090,10000091,10000092,10000093,10000094) Contract JobProfile - 97 ContractType - 10204687 Location - 75 Classification - 474 CostCenter - 53 Salary Scale  - 10300574 Department - 96 writtenLaborAgreement - 10524364 onCallAgreement - 10524365 mainOrAncillaryContract - 10524210 probationaryPeriod - 7145 EmploymentType - 7393 The value list endpoints return a list of codes and descriptions.

  This API is intended for recruiting systems and allows them to get the data needed for the recruiting process and send the candidate to be hired.   Candidates Technical flow The candidate endpoint is asynchronous: The recruiting sends in the new hire or contract change. Youforce will Validate the incoming data Trigger Id Scan (optional) Start a process based on configuration of the customer The recruiting system checks if the hire has been accepted. Steps 3 is critical. The process is only accepted by Youforce when the status is 'Completed'. It is the responsibility of the recruiting system to check if the hire is successfully trigged by based on the entered data. There are no user feedback mechanisms in Youforce that inform a hiring manager that the new hire has not been accepted by Youforce.   Candidate data Property Description Mandatory Example Data type candidateID The ID of the candidate in the recruiting system. This field is available as free field in the Core for Reporting purpose. Yes 0001 string PersonData Fields related to the person       PersonalDetails: last name, first names, date of birth, etc       PhoneNumbers: list of phone numbers One is mandatory     emailAdress: Private email address to contact the candidate. Yes candidate@private.com string Addresses: list of addresses       PersonalDetails Fields related to personal data         lastNameAtBirth: The last name at birth of the candidate. Also the family name.     string   lastNameAtBirthPrefix: The prefix of the last name at birth.     string   knownAs: The name which is used by the candidate as his first name.     string   initials: The initials of the candidate.     string   firstNames: The official given names of the candidate.     string   lastName: The last name the candidate is currently using.     string   gender: The gender of the candidate.   (0) Not known (1) Male (2) Female (9) Not applicable To use 0 and 9 values, they must be configured in the core system. string   birthDate: Date of birth of the candidate.     DateTime   birthPlace: The place of birth of the candidate.     string   birthCountry: The country of birth of the candidate.     string   primaryNationality: The nationality of the candidate.     string   titlePrefix: The formal title which will be used as a prefix before the name.     string   titleSuffix: The formal title which will be used as suffix after the name.     string   maritalStatus: The marital status of the candidate.     string   lastNamePreference: A code that indicates the preferred last name of the employee. for instance last name at birth last name partner last name partner + last name at birth last name at birth + last name partner     string   lastNamePartner: The partner last name.     string   partnerNamePrefix: The prefix of the partner last name.     string   socialSecurityNumber: Social Security Number of the candidate.     string phoneNumber details of the phone number         type: home, mobile   home string   number   + 31 0624829858 string Address Fields related to the address of the candidate       type: home, postal   home string streetName: Street name   Wamberg string number: House number   69 string NumberAdditional: additional number   34 string locationDescription: location     string postalCode: Postal code   1083 CV string city: City   Amsterdam string region: Region     string country: Country   The Netherlands string ApplicationDetails Fields related with the application       vacancyNumberHR: Vacancy number in the HR Core systems. With this field the core system can check if the position is still open.   001 string vacancyNumberATS: Vacancy number in the Applicant Tracking System. This field is available as free field for Reporting purpose.   1001 string offerApproveDate: Date that the offer is approved in the ATS system. It is the date that the recruitment process ends and the onboarding of the new employee can start.   01-01-2021 DateTime NewEmployement Fields related to the new employement       payrollClient: The Id of payroll client in the core systems.   B2020 string payrollCompany: The Id of payroll company in the core system. Yes C2020 string collectiveLaborAgreement: Id of the collective labor agreement.   CAO01 string hireDate: Proposed hire date of the Candidate. Yes 01-01-2021 DateTime endDate: If the contract is for a given time, this contains the end date of the employment.   31-12-2021 DateTime contractType: Type of the contact. Yes 01 string probationPeriod: Indicates if a probation period is applied to the contract.     boolean probationPeriodDuration: Duration of the probation period.     string probationPeriodEnddate: End date of the probation period.   31-03-2021 DateTime employeeType: Type of employment like Internal employee, contractor, etc. Yes 001 string organizationalUnit: Id of the organization unit of employment. Yes OU1 string jobProfile: Job profile of the employment. Yes JP1 string establishmentUnit: The logical code of location or establishment unit where the work is performed mainly in accordance with the contractual arrangement.   EU1 string amountOfHours: Amount of working hours. Yes 40 string Salary: Fields related to the salary.       OtherBenefits: List of other benefits.       Salary Fields related to the salary       salaryType: Type of salary     string SalaryPeriodicity     string SalaryAmount     string ContractSalary     string SalaryScale     string SalaryGrade     string RPSFactor     string HourlyRateAmount     string HourlyRateScale     string hourlyRateGrade     string Benefit Fields to describe other benefits       benefitCode: Code of the benefit.   BEN01 string value: Value of the benefit.   1000 string CurrentEmployment Fields related to current employement if exists.       PersonCode: Code of the person in the existing contract.   1000250 string employmentCode: Code of the employment in the existing contract.   1 string customFields                                                           customField1     string customField2     string customField3     string customField4     string customField5     string customField6     string customField7     string customField8     string customField9     string customField10     string customField11     string customField12     string customField13     string customField14     string customField15     string customField16     string customField17     string customField18     string customField19     string customField20     string customField21     string customField22     string customField23     string customField24     string customField25     string customField26     string customField27     string customField28     string customField29     string customField30     string   Vacancies DRAFT ⚠️ This is a draft endpoint. Vacancy data cannot be exposed at this moment. Please reach out to our community for more info.  Vacancy data Property Description Example Data type VacancyCode Unique vacancy number in the HR Core Self Service. This job request number is unique within the tenant. VAC0012 string Title Title of the Vacancy Case manager string organizationUnit Logical code of the organization unit HR01 string payrollCompany Logical code of the company B01 string recruitmentChannel Channel in which the recruitment systems will publish the job request. extern string jobProfile Logical code of the Job profile CMAN string jobLevel Required level of the job like instance Junior, Medior or Senior Medior string jobFamily Logical code of the Job Family HR string employeeType Type of employee Intern string amountHoursWeek Amount of hours a week 40 int contractType Contract type temporal string contractualDuration Duration of the contract. Only relevant contract type is temporal. 1 year string establismentUnit The logical code of the location or establishment unit where the work is performed, mainly in accordance with the contractual arrangement. AMS string numberOfPositionsRequired Total number of requested positions 5 int ApprovalDate Approval date of the job request 2020-12-20 DateTime startDate Start date of the job request 2021-01-01 DateTime endDate End date of the job request 2021-04-01 DateTime owner Manager of the job request J. Janssen string ownerEmailAddress Email address of the owner of the job request j.jansen@visma.com string RecruitmentReason Indicates the reason for this new position. For instance because it is new position, extension of existing position or replacement of an existing person on a position. Replacement string SalaryIndication Indication for the salary, for instance a range like: 1500 - 1800 euro or a maximum: max 2000 euro or a scale: Scale 10 Schale 10 string ExperienceLevel ExperienceLevel 4-6 string Extensions List of additional fields configured in the HSS and the API     key   string value   string   ID scan Customers can enable a Visma|Youserve ID Scan as part of their Recruiting API connections. This will increase data quality and ensure efficient administrative onboarding process. This is optional and needs to be enabled per customer.  The ID scan will complement or overwrite the data send by the recruiting system The ID scan will be triggered once the candidate has been received from our system. The candidate will receive an invite to scan his identity document and complete his data. The following data will be captured from the ID document: Birth names (incl. prefix)  Initials BSN   Nationality Birthdate Birthplace Gender Doc type Document number Document Registration Date Document Expiry Date The following data will be entered manually be the employee: Firstname to use + prefix Lastname to use + prefix Bankaccount (IBAN - minimal validation) Home address (street, number, postal, place, country) Partner last name + prefix  Title for Title after   ID Scans retention policy Successfully processed IDs will be forwarded as attachments in the triggered Hire or Contract change process in Self Service. The Self-Service retention & archiving policies are applicable for these attachments.  The service responsible for scanning the IDs will retain IDs as follows:  Successfully processed ID will be removed after 24 hours. An ID is processed when the Recruiting API has retrieved the scan from the ID scan service. Unprocessed ID will be removed after 2 weeks. So when the recruiting API was unable to fetch the ID scan for 2 weeks, the IDs will be automatically removed. 

Within API for BI systems there are CSV files. These files contain 2 major components, that is the ID and ParentID collumn.    In the attachment you can see the key elements (Entities) with their respective ParentID. This knowledge is necessary for knowing the relations between the key elements (Entities).   Attachment is stored as txt file, but it can be downloaded and converted to .json.

  The Learning API is intended for Learning Management systems and allows you to: Read employees and organizational structures from Youforce to update the learning system Upload certificates to the Youforce Personal File system of the customer Domain model     Concepts Employees The object employee contains all personal and employment details of an employee. Object attributes An employee is a person with one or more employments. Attributes person details Attribute Description id Unique id for the Person row within the tenant personCode The logical person code of the employee Initials The initials of the employee. firstNames The official given names of the employee as stored in the HR Core system KnowAs The name which is used by the employee as his first name lastNameAtBirth The last name at birth of the employee. Also known as the family name lastNameAtBirthPrefix The prefix of the last name at birth lastName The last which is currently used  by the employee as his last name lastNamePrefix The prefix of the last name as used currently  nameAssembleOrder Code of the assemble order that the core system uses for the last name. The assembly order is depending on the core system and the logic behind it. partnerName The partner last name partnerNamePrefix The prefix of the partner last name titlePrefix The formal title which will be used as a prefix before the name like Doctor, Professor, et cetera titleSuffix The formal title which will be used as postfix after the name like MSc or Master of Science gender Gender of the person. Supported values are Male / Female. Note: other type of genders will be shown as Not Known birthDate Date of birth deceased Indicated if the employee deceased  UserUID Digital Identity of the user from the portal emailAddresses type address List of the addresses of the employee.  The fields are: type like Business, Private, et cetera address Addresses type street houseNumber houseNumberAdditional locationDesignation postalCode city region country List of the addresses of the employee.  The fields are: type like Home, Post, et cetera street name house number house number additional Location designation Postal code City Region Country code phoneNumbers type number list of phone numbers of the employee type like Business, Home, Mobile, et cetera number communicationLanguage Communication language   Attribute employment details Attribute Description employeeID Technical and unique id. the Id is unique within the entity and tenant. employeeCode Code of the employee employmentCode Logical code of the employment company Unique (alphanumeric) identifier of the company  with which the contract is concluded hireDate The hire date of the employment dischargeDate The end date or discharge date of the employment. originalHireDate The first hire date or original hire date of an employee within the organization. employmentType Type of employment with a short name for type like Internal employee, contractor, "Wachtgelder" jobProfile job profile code of the employment The job profile is a code that refers to the entity job profile organizationUnit organization unit of employment. The organization unit is a code that refers to the entity organization units workingAmount amountOfWork unitOfWork periodOfWork Work amount of employment.  The amount of work Unit of work that specifies the amount of work like "hours", "days", et cetera Period of work like "week" or "month" contractType Contract type of the employee. It is the code that refers to the entity contract type. costCenter Main cost center associated with the employee. It is the code that refers to the entity cost center. classification Classification of the employee. It is the code that refers to the entity Classification. location Location of the employee. It is the code that refers to the entity location. salaryScale Salary scale of the employee. It is the code that refers to the entity salary scale   Data mapping Attributes person details attribute HR Core Business personId Technical id of the employee in HRCB personCode 7014 - Uniek Persoonlijk ID (UPI) (If it is not filled in then the Medewerkercode - 22) Initials 25 - Voorletters firstNames 51 - Voornamen KnowAs 165 - Roepnaam lastNameAtBirth 24 - Achternaam lastNameAtBirthPrefix 26 - Voorvoegsel lastName 524 - Opgemaakte naam aanhef Note: In HRCB this field is combination of the  last name  and the  last name prefix lastNamePrefix #NA nameAssembleOrder 28 - Eigennaam code partnerName 27 - Naam Partner partnerNamePrefix 166 - Voorvoegsel Partner titlePrefix 94 - Titel voor titleSuffix 95 - Titel na gender 36 - Geslacht Mapping details: 1 or Man → Male 2, Vrouw, Woman → Female Other values will shown as Not Known birthDate 35 - geboorte datum deceased Based on the date of deceased. If the employee is deceased the boolean is set to  True 10302568 - Datum overlijden UserUID 10523564 - PING ID emailAddresses type address Business : 7212 - E-mailadres Prive: 7213 - E-mailadres Prive Addresses type street houseNumber houseNumberAdditional locationDesignation postalCode city region country Home: 391 - straat 392 - Huisnummer 393 - Huisnummer toevoeging 8099 - Locatie omschrijving 394 - Postcode 395 - Woonplaats 34 - Woonland   10205283 Regionaam Buitenland  Postal: 7572 - Straat Postadres 7573 - huisnummer Postadres 7574 - Huisnummer toev. adres 8100 Locatie omsch Postadres 7575 - Postcode Postadres 7576 - Plaats Postadres 7571 - Land 8101 Regionaam Buitenland phoneNumbers type number Home : 7376 - Telefoonnummer prive Mobile : 7377 - Telefoonnummer mobiel Business : 7374 - Telefoonnummer intern addresses   communicationLanguage   10   Attribute employment details Attribute HR Core Business employeeID technical ID of the employee in HRCB employeeCode 22 - Medewerkercode employmentCode #NA company 18 - company code   hireDate 39 - Datum indienst dischargeDate 10520479 - Geplande laatste datum indienst originalHireDate 308 - Datum indienst organisatie employmentType 7393 - Type Medewerker jobProfile 97 - functie organizationUnit 6000 - Organisatorische eenheid workingAmount amountOfWork unitOfWork periodOfWork amount of work = 465 - Uren periode    perodOfWork = 463 - Dagen / uren per  *HRCB supports only amount of work in "hours" parttimePercentage is not available contractType contract type = 10204687 costCenter cost center = 53  classification classification = 474  location location = 75 salaryScale salaryScale = 10300574   Users The object User contains the User Identity for Single Sign-On. The User Identity is stored in the User Management System of the Youforce portal and can be used to support Single Sign-On. For HR Core Business the User Identity is already part of the employee endpoint. Object attributes attribute example description id c7e230db-2a7f-4ef0-ad1d-9d30e7d94a2f User Identity of the employee for Single Sign On. sourceId XX123456 not relevant within the learning domain identityId null not relevant within the learning domain   Organization units The object Organization Units will provide all HR Data regarding the organization structure, like business Unit, department. Next to that, it describes in what way these are related to each other. Based on the organizational structure it’s clear ‘which' department is responsible for 'what’. Object attributes The organization unit and the role assignment how the organization is structured and who is responsible in which role.   Attributes Organization Unit Attribute Description id Unique Id of the organization Unit shortName Logical code of the organization Unit fullName Logical name of the organization Unit parentOrgUnit Id of the parent organization Unit In some core systems this relation can changed in during the timeline of an organization Unit. organizationUnitType Type of organization Unit manager Manager of the organization unit* *Only for HR Core Business. For HR Core Beaufort the manager is part of the role assignment managerPersonCode Person code of the manager   Attributes Role Assignment Attribute Description id Unique Id of the record OrganizationUnitId Id of the organization unit the role assignment is effective for roleCode Code of the role. For instance the role manager is identified with the role code MGR. personCode Person who have this role for the specific organisation unit. The person code is a reference to the Person code in the employee personId Person who have this role for the specific organisation. The person id is a reference to the Person id in the employee table startDate Start date from which the role assignment is valid for that employee endDate End date from which the role assignment is valid for that employee   Data mapping Attributes Organization Unit Attribute HR Core Business id Technical id from HRCB   shortName 548 - code OE fullName 549 - Naam OE parentOrgUnit technical id of the parent Org unit organizationUnitType #N/A managerId 7137 - manager   Attributes Role Assignment Attribute HR Core Business id Technical id from HRCB   OrganizationUnitId 548 - code OE roleCode 549 - Naam OE personCode #N/A personId Reference to the Person Id startDate #N/A endDate #N/A   Job profiles Object attributes The object job profile contains the following attributes. Attribute Description shortName short name of the job profile fullName full name of the job profile jobFamily job family to which the job belongs.   Data mapping Attribute HR Core Business shortName Functie code fullName functie naam jobFamily Job family   Companies Object attributes The object company contains the following attributes. Attribute Description id identifier of the company code company code fullName full name of the company ValidFrom Start date of the version of the company ValidUntil End date of the version of the company Data mapping Attribute HR Core Business (Supported level: Client) id mutkey code company code fullName company name   Contract types Object attributes The object contract type contains the following attributes. Attribute Description code contract type code fullName full name of the contract type ValidFrom Start date of the version ValidUntil End date of the version Data mapping Attribute HR Core Business (Supported level: System) code contract type code fullName contract type name   Employment types Object attributes The object employment type contains the following attributes. Attribute Description code employment type code fullName full name of the employment type ValidFrom Start date of the version ValidUntil End date of the version Data mapping Attribute HR Core Business (Supported level: Client) code employment type code fullName employment type name   Cost centers Object attributes The object cost center contains the following attributes. Attribute Description code cost center type code fullName full name of the cost center ValidFrom Start date of the version ValidUntil End date of the version Data mapping Attribute HR Core Business (Supported level: Client) code cost center code fullName cost center name   Classifications Object attributes The object classification contains the following attributes. Attribute Description code classification code fullName full name of the classification ValidFrom Start date of the version ValidUntil End date of the version Data mapping Attribute HR Core Business (Supported level: Client) code classification code fullName classification name   Locations Object attributes The object location contains the following attributes. Attribute Description code location code fullName full name of the location ValidFrom Start date of the version ValidUntil End date of the version Data mapping Attribute HR Core Business (Supported level: Client) code location code fullName location name   Salary scales Object attributes The object salary scale contains the following attributes. Attribute Description code salary scale code fullName full name of the salary scale ValidFrom Start date of the version ValidUntil End date of the version Data mapping Attribute HR Core Business (Supported level: Client) code salary scale code fullName salary scale name   Job families Object attributes The object job family contains the following attributes. Attribute Description code job family code fullName full name of the job family ValidFrom Start date of the version ValidUntil End date of the version Data mapping Attribute HR Core Business (Supported level: System) code job family code fullName job family name   File upload With the documents endpoint files, certificates and other documents can be uploaded for an employee to the Visma Personal File System (Personeelsdossier).   Asynchronous file upload Learning systems can upload files, like certificates, diplomas for individual employees to the Personal File System of Visma Raet. The file upload is an a-synchronized process. After the file is uploaded the consumer will receive a ticket Id, which can be used to monitor the process of the file upload.        

  MLM API The available API’s of Visma | YouServe are developed corresponding with the data which is required for a specific HR domain. This MLM API has an ‘outside in’ set up, which means that each domain contains only the data and endpoints they need. The API’s support all common and domain-specific fields. For instance, the social security number is only available in domains with a legitimate reason, like Medical Leave Management. In other domains, other fields could be available. By using customer-specific ‘extensions’ it’s possible to add extra fields for an API user. This Medical Leave API will expose the necessary data which is needed to do your sickness case management according to the Dutch law ‘Wet Poortwachter’. Currently, we support the data entities People, Organisation Units, Sickness registrations, Value lists, Maternity Leaves, RoleAssignments, JobProfiles & Companies by exposing these via different endpoints.    Handle full loads & changes By calling the API the user will by default retrieve the tenant-specific data in full loads. In cases the user prefers to fetch only the changed data, we provide the possibility to use the parameters ‘ChangedAfter' & ‘ChangedUntil’ (see example).   Example date-time format : changedAfter - 2020-08-21T00:00:00.000Z changedUntil - 2020-08-21T12:01:46.077Z   Pagination of the result set To reduce the load of an endpoint each endpoint supports paging. In case the results of an endpoint contain more than 500 records, a ‘nextLink tag’ is available to retrieve the next page of the result. The nextLink tag is part of the body of the response and is also returned in the header of the response.   Example of nextlink in the in the body: "nextLink": "/persons?pageToken=20220207T1409148404911Z-20210121-B2011&take=500"   Example of nextlink in the header: x-nextlink: /persons?pageToken=0GXW0HLDWLoPqg3c63IGhbQuQhYB9mixdwbEP4+w52UUGnxYuKqsNBNDvK03lnoH&take=500" The nextLink indicates that there are more pages to load. If there is no nextLink available, this means that it’s the last page of the result set. Handle deletions The existing endpoints will provide the API consumers a status field that says something about the (in)active status of a specific record. For example in situations where sickness cases were deleted in the core system. The response bodies of the endpoints will have the following flag : "iD" : "123456" "IsDeleted":"false" The active value will be stated as “False” and an inactive (deleted) record will be stated as “True”. All the remaining fields in the deleted records will be empty and not visible in the output anymore. Historical, current & future data The different endpoints in the MLM API provide the most accurate data corresponding with the different data entities (Employee; Employments, Sickness cases, etcetera.). By executing full loads (and changed) the API exposes default data until 4 years back in history (from today’s date). Besides historical data also future changes will be exposed via the API. All these different data sets will show in ‘versions' by using a ‘ValidFrom’ and a “ValidUntil’ date. These ‘ValidFrom’ and ‘ValidUntil’ are functional dates which are sent to the API by the Visma core systems along with the corresponding data. These dates indicate the duration for which this version of the entity is valid. This makes it possible to expose for example contract details of an Employee multiple years back in time and also the future changes. In case a future change is added to the core system (from 24 hours p/w to 32 hours p/w per 01-01-2021) the API exposes all these versions in ‘time slices’. EXAMPLE OF RECORDS VERSIONS In the example below, the employee changes his working hours on 01-11-2018 into 32 hours. After this change, the system creates a new version of the record with a validFrom and validUntil. On 01-04-2019 he becomes UX designer in the UX team, so the next version is created. Response times API Visma Verzuim (a.k.a. DWC) is a Visma | YouServe partner that integrates with Youforce for employee, organization and sickness data. The data is made available to Visma Verzuim using the Youforce API for Medical Leave Systems (In short: ‘MLM API’).  The Youforce APIs are optimized for availability and scalability: the data is being ‘pre-processed’ for the API consumer. In this way we ensure that data is always available to integrated systems.  Pre-processing means the data is stored in a read optimized database to which the API is connected. The pre-processing also takes data authorization into account. In this way the API and HR Core system remain responsive when dealing with peak loads from consuming systems.  As a consequence it takes time before transactions in Youforce are available to other systems. This is known as ‘stale data’. The delay is normally within 10 to 30 minutes. Structural delays of more than 30 minutes are considered an issue.  Versioning of the different endpoints Some endpoints of the Medical Leave API might offer you multiple versions. Currently, the /employees endpoint has two functional versions. The technical usage of the different versions will be explained below. SWAGGER : In the Swagger tool this can be executed by switching the version in the right top bar 'Select a definition’ (see example).     After selecting the right version (f.e. V2), the corresponding version will show up in the Swagger documentation.     POSTMAN: In the Postman tool versioning can be managed by changing the Key 'Accept-Version' to 2.0 (see example). Entity model The MLM domain model contains the following entities     Endpoint Entity Description Employee endpoint Person A natural person. In HR it is more common to talk about employees, but the entity Person is broader than the entity employee. The entity could also contain Persons without any employment with the employer, like contact persons, suppliers, etc. Employee An employee is a person who had, has, or will have employment with the employer.  In natural language, we talk about employees, old employees or former employees.  Employment An Employment or Employment relationship defines the official relation between the employee and the employer. The employment can be based on multiple contracts as long it describes one continuous period of which the employee was employed to the same employer. Sickleave endpoint Sickness leave A sickness leave describes an uninterrupted period of absence because of sickness. Within this period an Employee can be partially recovered, but the sick leave will ends when the Employee is fully recovered. Maternity Leaves endpoint Maternity leave The maternity leave period that the employee is absent because of maternity leave. Sickness related to the pregnancy before or after the Maternity leave is not part of the Maternity leave itself but are separate sickness leave. Company endpoint Company The (legal) company as know by the core system Note: not all Core systems support the legal company, but only the Payroll company. There could be some payroll reasons to split a legal company into 2 different Payroll companies. For instance, if the legal company supports more than one payroll period (e.g. Month + 4 weeks). In that case, the official legal company does not exist. OrgUnits endpoint Organizational Unit The organization structure describes the organization in terms of Business unit, department, teams, etc. and how there are related to each other. Based on the organization structure it's clear how the organization is structured and "which" department is responsible for "what" RoleAssignments endpoint Role Assignment The role assignment describes "who" is responsible for "which role"  for "which period" for the organization unit. For instance "who is the manager" or "who is the financial controller", etc. JobProfiles endpoint JobProfiles All job profiles of the organization.    User The user account of a single employee   Based on the HR domain model we’ve defined the following endpoints : Endpoint GET /employees (current versions)  Endpoint GET /contracts (all versions)  Endpoint GET /persons (all versions)  Endpoint GET /organizationUnits (all versions)  Endpoint GET /sickleaves (all versions)  Endpoint GET /maternityleaves (all versions)  Endpoint GET /jobprofiles (all versions)  Endpoint GET /roleassignments (all versions)    How to ‘match’ entities? As a user, you are able to ‘match’ corresponding datasets, based on entity-specific unique identifiers. These specific keys per entity are unique and do not change during time.

  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  

This API is intended for Work Force Management systems and allows them to get the data needed for Workforce management systems who are responsible the planning of employees of an organization: Retrieve employee data from Youforce Retrieve organizational structures from Youforce Retrieve job profile information from Youforce

  IAM API This API is intended for identity & access management systems and enabling the provisioning of users in other systems like Active Directory or IDP’s: Retrieve employee data from Youforce Retrieve organizational structures from Youforce Retrieve job profile information from Youforce   Model   Pagination The IAM API supports pagination with the help of a nextToken. With the help of the following properties:  dateTime ,  validFrom  and  id  a “bookmark“ is generated ensuring no records are “lost“ when skipping through pages. Below a breakdown of the nextToken url generated at the end of the response body.     Next page token - Token generated at the end of the resultset page Date timestamp - The date timestamp of the last record of the result set page validFrom - The  validFrom  of the last record of the result set page Id - Primary key of the last record of the result set page.   Person layer in HR Core Business An additional requirement to use the Persons endpoint: the Person layer needs to be enabled in HR Core Business.