Knowledge base YouServe API's

API Statuses Concept APIs with this status are still under development and the development team is still making changes. Only a sandbox is available to start testing and the API cannot be used with customer environments.  Controlled Available (CA) APIs (or API versions) with this status are not ready yet to be rolled out to the complete customer base: It is available to a few access partners Connections of an access partner to the customer environment (tenant) are put on a waiting list, and it will take time before the connection is accepted There can be functional limitations of these APIs Controlled Available APIs have the usual security and support level. General Available (GA) APIs (or API versions) with this status are available to all access partners. The API can be used by all customers who use any of the HR Core systems that are supported by this API. Deprecated The API (or API version) is being phased out. We do not accept any new connections on this API (version). We will ask our access partners to move to another interface API. See also your Service Level Agreement   Life cycle policy We aim to provide you with a policy for releases and support for older versions for a consistent and predictable experience. Different types of changes The life cycle of any API products has dependencies on underlying products. Changes in those products may require changes to the API to support it. We distinguish between breaking changes and non-breaking changes. A breaking change is one that breaks the contract an API consumer depends on, either by a change in structure, behaviour or semantics. The release and support strategy makes a clear distinction in how these are managed. Major releases At times Visma YouServe may need to make larger changes to the API. Reasons may be changes to legal requirements, adding a large new feature to the API or an change in other products the API depends on. In these cases Visma YouServe may create a new major release of the API. We strive to also keep major releases backward compatible as much as possible but this may not always be possible. In case of breaking changes In general Visma YouServe aims to have a maximum of one major release per year. Each major release will be supported for at least 12 months after releasing the next major version. As a client to our API you will have to adjust your software to follow the major releases of our API as they will impact your integration. You must update your software to support the new API version as older API versions will be decommissioned following the policy as outlined above. Minor releases A minor release will never contain breaking changes, the are used to deliver incremental changes. Minor versions will not be visible in the path of the API. Visma YouServe can install minor updates in the standard release windows or as part of a hotfix and will communicate the changes as part of the release notes. Since this does not impact any existing functionality, we do not provide side-by-side support for multiple minor versions of the same major version: a minor upgrade just replaces the previous version. As a consumer of the API it is up to you to decide if you start using the newly available features. Announcing major releases Each release of a major API version will be accompanied by communication about the support lifecycle of the current version in the release notes. When approaching the sunset-date for an API product, we will actively reach out to inform any customers still using it: Communication When Where Recipient Announcement At the release of the new major version. Includes the date of decommissioning the previous version. General release notes All recipients of general release notes.   At the release of the new major version. Includes the date of decommissioning the previous version. Developer community Users of the Develope community 1st notification 6 months prior to decommissioning   Designated API contact persons 2nd notification 3 months prior to decommissioning   Designated API contact persons 3rd notification 1 months prior to decommissioning   Designated API contact persons     Spike arrest details Spike arrest is the way we protect against traffic spikes. Our APIs and backend can handle a certain amount of traffic, and the Spike Arrest policy smooths the traffic to the general amounts. Spike Arrest’s behaviour differs from what you might expect to see from the literal per minute values. Our default spike arrest is set to 100pm (100 requests per minute). That does not mean you can do 100 requests inside a 1-second. Spike Arrest smooths the number of full requests in a minute by dividing it into smaller intervals: Per-minute rates get smoothed into full requests allowed in intervals of seconds. For example, 100pm gets smoothed like this: 60 seconds (1 minute) / 100pm = 0.6-second intervals, or 1 request allowed every 0.6 seconds. A second request inside of 0.6 seconds will fail. Also, the 101st request within a minute will fail. When you exceed the policy, the API will return response code '429 - Too many requests' and you have to wait for the next time window.

  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.

  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 HR Core Business Retrieve organizational structures from HR Core Business Retrieve job profile information from HR Core Business.   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.    Retention time of data Retention time refers to the duration that data is stored and available in the API. In the context of GDPR legislation, it is important to define and enforce appropriate retention times to ensure personal data is not kept longer than necessary, aligning with principles of data minimization and privacy. Retention time can be defined at the API level per customer, giving them control over how long their data is stored for the purpose of APIs. To change the retention time you can create a support ticket. Please note that any changes to the retention time require a reload of the data to take effect. Each night, the system automatically evaluates and cleans up data in the API system, based on predefined retention policies. The retention time is calculated using a specific reference dates for each endpoint. The table below outlines the reference dates used per entity to determine the applicable retention period.   Endpoint reference date Companies validUntil Employees dischargedate Employments dischargedate Jobprofiles validUntil Organization Units validUntil Persons If a person has no employment, the person is no longer available in the API Role Assignments validUntil Valuelists validUntil   Example 1: Organisation Units Retention time = 30 days Data: New name for org unit C003 from "HR Advice" to "HR Advice corporate" per 1st of May 2025. { "id": "23590975", "shortName": "C003", "fullName": "HR Advice", "validFrom": "2020-01-01", "validUntil": "2025-04-30" }, { "id": "23590975", "shortName": "C003", "fullName": "HR Advice corporate", "validFrom": "2025-05-01", "validUntil": "9999-12-31" } (for demonstration means, not all data of the endpoint is shown) Retention policy, 30 days: The version (time slice) with "validFrom": "2020-01-01" to "validUntil": "2025-04-30" will be no longer available in the API on the 31st of May 2025. The 30 days of retention are passed.   Example 2: Employments Retention time = 90 days Data: no discharge date { "id": "40259407", "personCode": "1014", "personId": "1014", "employeeCode": "1014", "validFrom": "2020-01-01", "validUntil": "9999-12-31", "dischargeDate": "", "company": "500" } (for demonstration means, not all data of the endpoint is shown) No dischargedate is available, the employee is in service, employment will be available in the endpoint.   Example 3: Employments with dischargedate Retention time = 90 days Data: no discharge date { "id": "40259407", "personCode": "1014", "personId": "1014", "employeeCode": "1014", "validFrom": "2020-01-01", "validUntil": "9999-12-31", "dischargeDate": "2025-06-30", "company": "500" } (for demonstration means, not all data of the endpoint is shown) Retention policy, 90 days: The employment will be no longer available in the API on the 29th of September 2025. The 90 days of retention are passed at that time.      

Versions of the endpoint employees For the endpoint GET /employees there’ll be 2 versions available (status : sep ‘20). These versions are ‘header based’ available for API consumers.  The version is added to the header of the request: Example requesting v2.0 using postman   The functional difference between those versions is the following : V1 (DEPRECATED!) In this endpoint version we face a small issue that an employee in core system HRCB (r1) becomes a single employee in our MLM API output. As a result that a single person is returned multiple times in our API’s (see example below). Eventually this version will be phased out! Person: { personID : 123, name : Jan Jansen, address : ABC, contract : A1, validFrom : 01-02-2020, validUntil : 10-04-2020 } Person: { personID : 123, name : Jan Jansen, address : DEF, contract : B1, validFrom : 11-04-2020, validUntil : 10-06-2020 } Person: { personID : 123, name : Jan Jansen, address : DEF, contract : B2, validFrom : 11-06-2020, validUntil : 31-12-9999 }   V2 In this version V2 we’ve solved the above issue in V1, so we’ll return here in a correct way the current version of a unique person with the actual contract versions. We’ve included temporality on the ‘Person level' and also on the lower ‘Contracts level', so the API consumer is able to jump into conclusions very efficiently. Scenario : standard exposure / current person versions with current contract versions Person 1: { (current version) validFrom : 01-01-2020 validUntil : 31-12-9999 personID : 123, name : Jan Jansen, address : ABC, contract : A3, (current version) validFrom : 01-05-2020 validUntil : 31-12-9999 contract : B5 (current version) validFrom : 01-03-2020 validUntil : 31-12-9999 } Person 2: { (current version) personID : 345, name : Joke van der Laan, address : HJK, contract : A2, (current version) contract : B2 (current version) } …… Person 100 { (current version) personID : 964, name : Henk de Vries, address : VDW, contract : A1, (current version) contract : B4, (current version) contract : C1 (future version) contract C - version 1 validFrom 01-10-2020 --nextlink-- In the above V2 example we expose Person 1 with personId 123 who has two contracts (A, B). Each contract has its own versions. Contract A has two historical versions and one current version. Contract B has four historical versions and one current version. Scenario : active person has only one historical inactive contract The following scenario covers again Person 832 who’s having just one contract (A) which became historical (since yesterday). The endpoint will return his actual personal details with this (historical) contract data. So in case, there is no active contract, the response will show the last active contract version (latest historical). Person 72: { (current version) personID : 832, name : Piet van de Berg, address : DDS, contract : A3 (historical version) Scenario : active person is a ‘new hire’ with one future contract In the below scenario of Person 193, who’s having just one future contract (future hire). The /employee endpoint return actual person details with his contract details. Since there is no active contract, it will return the future contract version. Person 41: { (current version) personID : 193, name : John de Jong, address : HJA, contract : A1 (future version)

  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.  

  Swagger documentation The following swagger page gives an overview of the endpoints: Recruiting API   Endpoints Candidates Post candidate The endpoint Post candidate allows to send a candidate to be hired in the core system. This method returns the processId to check the status. POST https://api.youserve.nl/recruiting/v1.0/candidates There are 2 ways of calling this endpoint, with or without attachments. With attachments The header Content-Type should be: multipart/related; boundary="A100x"; (The boundary is the one you choose). The total size of the request (all files and request body) is up to 100MB and the allowed file types are pdf, docx, txt, jpg, jpeg and png. Files cannot be empty. The body should be splitted by sections, being the first one a json section with the candidate data as in the request without attachments. For each attachment, there will be 2 sections: json section: name of the file --A100x Content-ID: <content> Content-Type: application/json { "Description":"contract.pdf" } file section: content of the file --A100x Content-ID: <content> Content-Type: application/pdf %PDF-1.7 %·¾¬ª 1 0 obj <<  (this example is not complete) Process status After the candidate is posted to the API, the process can be followed with the status endpoint. The status of a process could be Pending, InProgress, WaitingOnValicare (if it is configured), Completed or Failed. Replace the ProcessId in the URL with the  processId  from the previous API call. GET https://api.youserve.nl/recruiting/v1.0/candidates/{ProcessId}   Checking the status of the hire is needed, because failed hires won’t be automatically reprocessed. It is necessary to correct the problem and send them again. Also it is possible to get a list of processes, filtering by status, created after and created before. GET https://api.youserve.nl/recruiting/v1.0/candidates/status GET https://api.youserve.nl/recruiting/v1.0/candidates/status?status=Completed GET https://api.youserve.nl/recruiting/v1.0/candidates/status?createdAfter=2021-09-01&createdBefore=2021-09-12   Vacancies DRAFT ⚠️ This is a draft endpoint. Vacancy data cannot be exposed at this moment. Please reach out to our community for more info.    GET vacancies The endpoint GET vacancies gives a list of vacancies of the tenant. This endpoint is available only with mock data for the sandbox tenant. GET https://api.youserve.nl/recruiting/v1.0/vacancies   Postman collection and environment As attachment you can find a zip file with the collection and the environment.    

  Q: How can I receive only changed records? A:  The From and To filter is available to receive changes in a given time range. The From and To filter option is available on most endpoints, except valueLists. Example employees: Returns (active) employee records that have changed within the provided date-time range.   https://api.youserve.nl/iam/v1.0/employees?from=2021-01-01T09:00:00.000Z &to=2022-01-10T14:00:00.000Z   Q: What does the 90 day retention policy signify? A:  At current, the retention policy on the data stored in for the IAM API is 90 days. Based on the following properties a record will be removed when the date defined for these properties is greater than 90 days in the past: validUntil  - all entities dischargeDate  - employments, employees endDate  - role assignments, assignments Q: Why do I see records with the with dischargeDates or endDates in the past? A: We support the notion of retroactive changes i.e. when a dischargeDate for an employment or endDate for an assignment is defined today for a date is set in the past. This can be the result of an administrative mistake. In this scenario, the record will remain available for 90 more days based on the mutation date (date when the change was made).   Q: Why do I not see all the properties mentioned in the data mapping document in my response? In the IAM API properties that do not have values defined in the core systems are hidden. For this reason there might be a different amount of properties available per record.   Q: What are extensions? A: Extensions are based on the customer-specific fields defined in the core application. These custom fields can be configured and returned as part of the API response body . As a customer I have a custom field named: “height“. As part of my integration it is important to know the height of my employees in order to validate their identity. With the extensions feature we are able to expose this field and value as part of the API response allowing the customer to validate the identity of employees with the help of their height. Extensions are only available for HR Core Business and for the Employees (employee entity) and Employments (contract entity) endpoint.   Q: Why do I have more than 1 record for my entities? A: As part of the IAM API we support support, historic, current and future changes. A change in the core is reflected by a new record in the IAM API, which can be referred to as “versions“. Each record has the following properties: validFrom - This reflects the date from which a record is considered valid, the “start date“ of the validity validUntil - This reflect the date from which a record is no longer valid, it’s “end date“ of the validity    

This article shows all available endpoints for the Onboarding API. 

What is the YouServe API? Through the YouServe API you can in integrate data and therefore giving your customers: an up-to-date list of the latest HR information in your application automatic on- and off-boarding of employees in your application HR Core system There is always an HR Core system in the centre of every customer implementation storing the employee data. With the API's we support  HR Core Business.   API library You can find the APIs at https://developers.youserve.nl/api-library   

Sandbox environment Single Sign-On Sandbox environment Q: Is there a test or sandbox environment available for developers? A: Yes, we have different a sandbox environment available. Please contact us if you want to access the environment. Single Sign-On Q: I want to use the API together with the Single Sign-On solution of Visma Raet. What should I know about that? A: For Single Sign-On you need to keep the User Identify of the employee in your system. This User Identity will be used to switch between the Youforce module and your application for a single employee.  

User (v3) The user endpoint supports the retrieval (GET) and update (PATCH) of user related data from HR Core. Base URL of user endpoint:   https://api.youserve.nl/iam/v3.0/users   GET Allows retrieving user related data from HR Core of a single employee. Data can be retrieved using several parameters: personcode or mutkey of the employee (getById).   PersonCode https://api.youserve.nl/iam/v3.0/users?personcode=[personcode]  The personcode matches the personcode in the endpoints Employees and Employments Example: https://api.youserve.nl/iam/v3.0/users?personcode=1012    getById https://api.youserve.nl/iam/v3.0/users/[id]  The id matches the mutkey of the employee which can be found in the endpoint Employees (employees.id) Example: https://api.youserve.nl/iam/v3.0/users/36457840    Datamapping Property Description Corresponds with HR Core field assignedIdentity (v2 property name: id) User id of the employee used in the Youforce authentication system (PING) or the Visma Connect Identity   Example:  c7e230db-2a7f-4ef0-ad1d-9d30e7d94a2f Toegekende identiteit (before: PING Identiteit) (NL) Assigned identity (before: PING Identity) (ENG)   Elementnumber: 10523564   loginPortalEmailAddress (v2 property name: identityId) Email address which is used for login of YouServe portal   Example: user@customer.com   NL: E-mail adres (Login Portaal) (before: Identity)   ENG:  Email address (Login Portal) (before: Identity)   Elementnumber: 7013   businessEmailAddress Business email address   Example: user@business.com     E-mail adres (zakelijk) (NL) Email address (business) (ENG)   Elementnumber: 7212   privateEmailAddress Personal email address of employee   Example: user@business.com   E-mail adres (privé) (NL) Email address (private) (ENG)   Elementnumber: 7213   employmentStatus (new per 17-10-2025) Status of an employee 0 = Future Hire (no login) 1 = Future Hire 2 = Active employment 3 = Out of service 4 = Never employed 5 = Out of service (no login)   Arbeidsrelatie status (NL) Employment status (ENG)   Elementnumber: 10529734   kindOfEmployment  (new per 17-10-2025) Indicator for external or regular employee 1 = Employee 2 = External Arbeidsrelatie soort (NL) Kind of employment (ENG)   Elementnumber: 10529728   vismaConnectId  (new per 17-10-2025) Visma Connect Identity. This value will be automatically populated when a user is created in Visma Connect   Example: 0ceee097-3b81-44a2-8cb4-1d0ce22dfad0   Visma connect identiteit (NL) Visma connect identity (ENG)   Elementnumber: 10530657 startDateLogin (new per 17-10-2025) Starting from this date an employee is able to login prior to the start of his contract. This date can be used as changeDate in the PATCH.   Begindatum login (NL) Startdate login (ENG)   Elementnumber: 10529730   hireDate (new per 17-10-2025) Date of hire for the employment This date can be used as changeDate in the PATCH. Datum indienst (NL) Date service (ENG)   Elementnumber: 39   * Either the startDateLogin is in the response or the hireDate. The following rule applies: startDateLogin is delivered when employee is not yet in service (today earlier then hireDate).  HireDate is delivered when the employee is in service (today is later or equal to hireDate)   PATCH Allows to update user related data in HR Core. Use the personcode or mutkey of the employee to update the data:   Examples: https://api.youserve.nl/iam/v3.0/users?personcode=1012  or https://api.youserve.nl/iam/v3.0/users/36457840     The following properties can be updated to HR Core: Property Description Corresponds with HR Core field businessEmailAddress Business email address   Example: user@business.com E-mail adres (zakelijk) (NL) Email address (business) (ENG)   Elementnumber: 7212   privateEmailAddress Personal email address of employee   Example: Johnson@yahoo.com E-mail adres (privé) (NL) Email address (private) (ENG)   Elementnumber: 7213   changeDate (new per 17-10-2025) The change in the PATCH will start from this date on forward. The date is the change date of the email addresses (business or private) which are in the body of the PATCH request. When changeDate is not part of the patch, the current date is used.   Reference date in HR Core   Using the changeDate: With the use of changeDate, a business or private email address can be added to HR Core before the employee gets in service.  The changeDate implies the date when the change of business or private email address is active in HR Core If the startDateLogin (see GET) is in the future, use this date as changeDate If the startDateLogin (see GET) has passed and the hireDate has not passed, use today as changeDate If the hireDate (see GET) has passed, use the hireDate (or any later date) as changeDate   Request body example:  { "businessEmailAddress": "user@business.com", "privateEmailAddress": "Johnson@yahoo.com", "changeDate": "2025-10-20" } Returns a 200 when successful   Notes with v3: Compared to v2 the id property can not be patched anymore. This is due to the changed functionality in HR Core. See release note HR Core.  Compared to v2, the employeeCode is no longer supported as a filter.