Knowledge base YouServe API's

Overview of all IAM endpoints including Swagger.

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.  

  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.      

Swagger documentation The following swagger pages gives an overview of the endpoint: IAM User endpoint  User endpoint   The user endpoint supports the retrieval of users and gives the ability to set the email address as identity for a user. The next methods are supported as part of the users endpoint. https://api.youserve.nl/iam/v1.0/users GET Allows retrieving a single employee based on employeeId for the tenant specified in the request header. https://api.youserve.nl/iam/v1.0/users(employeeId=12345) Supports the following parameter as part of the resource path: employeeId - The unique id assigned to an employee. This value is available in the Employees endpoint with the property PersonCode employeeCode. Returns a 200 OK when successful PATCH Allows to update or set an email address as identity for a specific user based on employeeId  (PersonCode employeeCode in Employees endpoint) for the tenant specified in the request header. https://api.youserve.nl/iam/v1.0/users(employeeId=12345)/identity Supports the following parameter as part of its request body: id- email address of the employee which is to be used for SSO { "id": "[email protected]" } Returns a 204 No content when successful Visibility of the change in Youforce portal Please note that updating the identity through this endpoint will update the identity in the Youforce authentication system will NOT show the values in Youforce portal Our authentication system is not running on the same service as the portal UI. The synchronization is just one way: Changes done in the authentication system direct will not reflect in the Youforce portal UI Changes done in this UI will reflect in the authentication system Datamapping Parameters Description Example Data type employeeId The unique id assigned to the employee by the HR Core 12345 string id User id of the employee used in the Youforce authentication system HR Core Business: (NL) PING Identiteit (elementnr. 10523564) c7e230db-2a7f-4ef0-ad1d-9d30e7d94a2f string sourceId Username of the user in the Youforce portal.  HR Core Business: (NL) Gebruikersnaam (elementnr. 61) XX123456 string identityId UPN/Identity in the customer authentication system that takes care of authentication HR Core Business: (NL) Identity (elementnr. 7013) [email protected] string

  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