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
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.
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 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
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 Youforce
Retrieve organizational structures from Youforce
Retrieve job profile information from Youforce
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.