IAM API - New version of the User Endpoint

[#1]

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": "user@customer.com"
}

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": "user@customer.com",
    "businessEmailAddress": "user@business.com",
    "privateEmailAddress": "Johnson@yahoo.com"
}

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.