News YouServe API's

The domain IAM API offers a user endpoint where specific user data can be retrieved, also the email addresses can be patched.

To support the changes in HR Core on the employee journey and to support the new YouServe IAM solution for user login to the YouServe portal, the user endpoint is updated.

If you use the user endpoint, please change as quickly as possible to the new improved version. The old version will be removed in Q1 of 2026.

In the new version we made some improvements:

• GET
  • The label of property id has changed to assignedIdentity according to renaming in HR Core
  • The label of property identityId has changed to loginPortalEmailAddress according to renaming in HR Core
  • New properties are added: 
    • employmentStatus, 
    • kindOfEmployment, 
    • vismaConnectId, 
    • startDateLogin (This date can be used as changeDate in the PATCH),
    • hireDate (This date can be used as changeDate in the PATCH)
  • Also the employeeCode is no longer supported as a filter. This was degraded already in v2 and no longer supported in v3.
• PATCH
  • To support access to the YouServe portal, a new property is added: changeDate. This property can be used to give a start date of the change in the PATCH. 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.

    • 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
  • In v2 the Id property could also be patched. In v3, the id property can not be patched anymore. This is due to the changed functionality in HR Core. See release note HR Core. 
  • Also the employeeCode is no longer supported as a filter. This was degraded already in v2 and no longer supported in v3.

The URLs of old and new versions:

• Version 3: https://api.youserve.nl/iam/v2.0/users 
• Version 2: https://api.youserve.nl/iam/v3.0/users 

For further reading on v2 and v3, check our user endpoint description. 

The IAM API offers a user endpoint where specific user data can be retrieved, also the identity can be patched. Check the documentation user endpoint v1 for way of working up till 1-3-2025.

In user endpoint v1, the data source for the endpoint is the Youserve portal with Raet IAM and ping as IDP.

We changed the source of the data to HR Core Business. This will solve current data conflicts and will be future proof when YouServe will move towards YouServe IAM with Visma Connect as IDP.

The new version of the User endpoint will be available with the url: https://api.youserve.nl/iam/v2.0/users. Getting and updating the data has slightly changed.

Check the documentation of user endpoint v2 in this article. 

Retrieving data: GET method

The Get method will deliver more properties as version 1: 

• Id (pingid),
• sourceid (username) and
• identityid.
• businessEmailAddress (new)
• privateEmailAddress (new)

Calling the Get method has changed.

Version 1: 

• https://api.youserve.nl/iam/v1.0/users(employeeId={employeecode})
• example: https://api.youserve.nl/iam/v1.0/users(employeeId=12345)

Version 2: 

In Version 2 we support retrieving the data by personCode and mutkey of employee:

https://api.youserve.nl/iam/v2.0/users?personcode=1012

or https://api.youserve.nl/iam/v2.0/users/36457840

EmployeeCode is also supported, but we advice not to use this, because employeeCode is not always unique for an employee.

• https://api.youserve.nl/iam/v2.0/users?personcode={personcode}
  • example: https://api.youserve.nl/iam/v2.0/users?personcode=12345
• https://api.youserve.nl/iam/v2.0/users/{id}
  • example: https://api.youserve.nl/iam/v2.0/users/36457840 

Please read all about this in the documentation of user endpoint v2. 

Updating data: PATCH method

Calling the Patch method has also changed.

Version 1: 

• https://api.youserve.nl/iam/v1.0/users(employeeId={employeecode})/identity 
• example: https://api.youserve.nl/iam/v1.0/users(employeeId=12345)/identity 

With in the request body: 

{
    "id": "[email protected]"
}

Version 2: 

• https://api.youserve.nl/iam/v2.0/users?personcode={personcode}
  • example: https://api.youserve.nl/iam/v2.0/users?personcode=12345
• https://api.youserve.nl/iam/v2.0/users/{id}
  • example: https://api.youserve.nl/iam/v2.0/users/36457840 

With in the request body (same as v1):  

{
    "id": "[email protected]",
    "businessEmailAddress": "[email protected]",
    "privateEmailAddress": "[email protected]"
}

Please read all about this in the documentation of user endpoint v2. 

The new version of the user endpoint is available starting from February 2025. 

You can move to the new version on your own pace. Both versions are active and supported.

Version 1 will be deprecated by July 2025.

In September 2020, we added a new version of the Employees endpoint to the MLM API.

For details on v1 versus v2, please read this article.

Per the first of July 2023, we are moving the old version 1.0 from deprecated to retired. This means we will stop the availability of the endpoint. 

If you still use this endpoint, we urge you to start using the Employees v2 version.

Q1: How do I know which version I use?

A1: If you don't use header variable Accept-version with version 2.0, you are using the v1.0

This indicates usage of v2.0

Q2: What are the differences between v1.0 en v2.0?

A2: All fields available in v1.0 are available on v2.0, except for 1 field. This concerns the personId field. The personId in v1.0 is the id field in v2.0. See below for an overview:

The mutkey of the employee is not available in v2.0. To identify employees, the personId and personcode can be used