Knowledge base YouServe API's

Overview of all IAM endpoints including Swagger.

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