IAM API FAQ

[#1]

• Q: How can I receive only changed records?
• Q: What does the 90 day retention policy signify?
• Q: Why do I see records with the with dischargeDates or endDates in the past?
• Q: Why do I not see all the properties mentioned in the data mapping document in my response?
• Q: What are extensions?
• Q:Why do I have more than 1 record for my entities?

 

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