Integration API for Identity & Access Management Domain (IAM) GENERAL AVAILABLE

1. Overview

Domain Purpose:
The IAM domain enables integration between HR Core HR Core and external Identity & Access Management systems. It provides essential HR data such as personal and contract information to automate security-critical processes like onboarding, offboarding and access provisioning of users in other systems like Active Directory or IDP.

Typical Use Cases:

• Automating account creation for new employees in IT systems
• Revoking application or building access when a person changes roles
• Syncing employee role changes to access control systems
• Syncing the AD identity with Youforce

Base URL:
https://api.youforce.com/IAM

Swagger page:
For more detailed information about the endpoints available in this API, please visit the Youforce IAM API Swagger page

Postman collection:
For a complete example, you can check our Postman collection

2. Domain model

3. Available endpoints

This is the list of available endpoints for this domain.
Take into account that the endpoints will show the information that has been already processed by HR Core. This means that changes in the recent future might be shown in the response of the APIs and not the current value.

3.1 Write-Back Contact Details

Update a person’s email address and/or phone number. For reading contact details, use the Persons endpoint — this entity is for writing only. Important: emailAddress and phoneNumber here write to the person’s work email and work phone number specifically, not their private email or mobile number.

Updating one person

POST /{domain}/v1.0/ContactDetails/{personCode}

Example

POST /iam/v1.0/ContactDetails/123456

{
  "emailAddress": "frits.bakker@example.com",
  "phoneNumber": "+31612345678"
}

Response — 200 OK

{
  "ticketId": "fede49ce-7043-482d-aba8-152478712c4b",
  "status": "None",
  "errorMessage": null,
  "contactDetails": [
    { "personCode": "123456", "emailAddress": "frits.bakker@example.com", "phoneNumber": "+31612345678" }
  ]
}

The write is processed asynchronously — a 200 OK here means the request was accepted, not that the update has completed. Keep the ticketId to check progress.

Updating multiple people at once

POST /{domain}/v1.0/ContactDetails/bulk

Body: an array of objects, each with:

Maximum 100 entries per request.

POST /iam/v1.0/ContactDetails/bulk

[
  { "personCode": "123456", "emailAddress": "frits.bakker@example.com" },
  { "personCode": "123457", "phoneNumber": "+31612345679" }
]

Response shape is the same as above.

Validation rules

• personCode must be numeric.
• The person must exist and be visible to your client (same authorization rules as the Persons endpoint) — otherwise you’ll get a 404.
• emailAddress: max 99 characters, must be a valid email format.
• phoneNumber: max 15 characters; optional leading +, otherwise digits, spaces, dots and hyphens.
• At least one of emailAddress/phoneNumber is required per person.

Checking the outcome

GET /{domain}/v1.0/ContactDetails/{ticketId}/status

GET /iam/v1.0/ContactDetails/fede49ce-7043-482d-aba8-152478712c4b/status

{
  "ticketId": "fede49ce-7043-482d-aba8-152478712c4b",
  "status": "Complete",
  "errorMessage": null,
  "contactDetails": [
    { "personCode": "123456", "emailAddress": "frits.bakker@example.com", "phoneNumber": "+31612345678" }
  ]
}

Response codes

4. Security and Scopes

All available endpoints are secured using OAuth 2.0 and protected by scopes.

5. Pagination & Filtering parameters

Learn how to efficiently manage large amounts of information by using pagination and filtering parameters to improve performance and user experience.

Pagination Parameters:

These parameters control the pagination of API results:

• take: Use this parameter to retrieve a certein amount of registers per call, being the minimun value 1 and the maximum value 1000.
• skip: Use this parameter to skip a certein amount of records. Use it for offset-based pagination.
• nextLink: For large paginated responses, if there are more registers than shown in the output, we will provide a continuation token that you can use in the next call to get the next page.
  

Date Filtering Parameters:

The latestSync field in the response reflects the last synchronization datetime (creation or modification dates) we stored because we received an update from the HRCore. So it is not related to the dischargedate value.
These parameters filter records based on this latestSync field:

• from: Use this parameter to filter records based on creation or last modification dates and retrieve records which modification date is greater or equal to the value in the filter → records that have latestSync datetime >= from
• to: Use this parameter to filter records based on creation or last modification dates and retrieve records which modification date is less or equal to the value in the filter → records that have latestSync datetime <= to
  

Filters on validity of a record:

• validOn: Use this parameter to filter temporal entities that are valid on a specific date (e.g., contract validity based on its start and end dates). This filter is meant to be used in combination with From and To parameters. For example, with From and To you will get the Employments that are modified in a specific range, and with validOn you will limit the response to the records that are active on a specific date.
  Available endpoints: timelines, assignment and role assignment endpoints.
  

Other Parameters:

• isActive: Use this parameter to distinguish between active or deleted records. Active means that it is still in the HR Core database but it has not been deleted from there. It doesn’t correspond to the block field in HR Core.
  Available for all endpoints.
  Example 1:
   - we have a record that is active (not deleted in HR Core)
   - today is 01/12/2025
   - historical days is set at 60 days in the subscription (Configuration API)
   - the discharge date is 01/11/2025 (within the historical days window)
   → then the record will be returned in the API
  Example 2:
   - we have a record that is active (not deleted in HR Core)
   - today is 01/12/2025
   - historical days is set at 15 days in the subscription (Configuration API)
   - the discharge date is 01/11/2025 (outside the historical days window)
   → then the record will NOT be returned in the API
  Example 3:
   - the record has been deleted on 01/12/2025 from HR Core (it is not active)
   - today is 01/12/2025
   - historical days is set at 75 days in the subscription (Configuration API)
   - the discharge date is 01/11/2025 (within the historical days window)
   - It is within the 7 days after its deletion and:
          - the filter isActive is true → then the record will NOT be returned in the API
          - the filter isActive is false → then the record will be returned in the API
          - the filter isActive not provided → then the record will be returned in the API
  Example 4:
   - the record has been deleted on 10/11/2025 from HR Core (it is not active)
   - today is 01/12/2025
   - historical days is set at 75 days in the subscription (Configuration API)
   - the discharge date is 01/11/2025 (within the historical days window)
   - it is not within the 7 days after its deletion
   → then the record will NOT be returned in the API (regardless of the value of isActive parameter)
  

• personId, personCode: Use one of these parameters to filter indistinctly by the code of an specific individual.
  Available endpoints: Assignment, CostAllocation, Person, RoleAssignment and PlannedChanged.
• company: Use this parameter to filter by company field.
  Available endpoints: Employment.
• organizationUnit: Use this parameter to filter by department or team structure.
  Available endpoints: Employment.
• shortName: Use this parameter to filter by the short name of an organization unit or job profile depending on the endpoint.
  Available endpoints: JobProfile, RoleAssignment and OrganizationUnit.
• statusFrom: Use this parameter to filter records based on the status date field and retrieve records which status date is greater or equal to the value in the filter.
  Available endpoints: PlannedChanges.
• statusTo: Use this parameter to filter records based on the status date field and retrieve records which status date is less or equal to the value in the filter.
  Available endpoints: PlannedChanges.
• status: Use this parameter to filter records based on the status field. The possible values are: pending, processed, blocked and rejected.
  Available endpoints: PlannedChanges endpoint.
• employmentType: Use this parameter to filter by the employment type code.
  Available endpoints: Employment.

6. Deprecated Endpoints

List of Deprecated Routes:

• GET /v1.0/EmploymentTimelines:
  This behavior has been incorporated as part of the Employments endpoint –> GET /v1.0/Employments/Timelines
  
• GET /v1.0/EmploymentTimelines/{id}:
  This behavior has been incorporated as part of the Employments endpoint –> GET /v1.0/Employments/Timelines/{id}