IAM API - New version of the User Endpoint: v3

[#1]

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.