IAM User endpoint v3

21-10-2025

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: [email protected]

NL: E-mail adres (Login Portaal) (before: Identity)

ENG: Email address (Login Portal)
(before: Identity)

Elementnumber: 7013

businessEmailAddress

Business email address

Example: [email protected]

E-mail adres (zakelijk) (NL)

Email address (business) (ENG)

Elementnumber: 7212

privateEmailAddress

Personal email address of employee

Example: [email protected]

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: [email protected]

E-mail adres (zakelijk) (NL)

Email address (business) (ENG)

Elementnumber: 7212

privateEmailAddress

Personal email address of employee

Example: [email protected]

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": "[email protected]",
    "privateEmailAddress": "[email protected]",
    "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.