1. Overview
Domain Purpose:
The Enterprise domain enables integration between HR Core and external systems who are responsible for employees within an organization.
Typical Use Cases:
Base URL:
https://api.youforce.com/enterprise
Swagger page:
For more detailed information about the endpoints available in this API, please visit the Youforce Enterprise API Swagger page
Postman collection:
For a complete example, you can check our Postman collection
2. Domain model
3. Included entities
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.
| Entity | Description | Access capabilities |
|---|---|---|
| Assignments | Allocation of specific tasks or duties to an employee within an employment. For example, an employee is assigned to a different department as a temporary replacement or to help another department without changing his own employment. HR Core: Inzet | READ |
| Contact Details | It refers to the information used to reach or communicate with a person, such as phone numbers and email addresses. Note that, for reading purposes, this information is available in the Persons endpoint. | WRITE |
| Contract Types | Reference table that exposes the type of contracts available. HR Core: Soort contract | READ |
| Cost Allocations | Regarding the distribution of financial resources or expenses across different departments or projects, it is the cost center of an employee. An employee can have multiple cost allocations. HR Core: Loonverdeling | READ |
| Cost Centers | In the entity Country are exposed the possible code and description of the different cost centers. HR Core: Kostenplaats | READ |
| Country | In the entity Country are exposed the possible countries recorded as a reference table. HR Core: Land | READ |
| Employments | The formal relationship between an employer and an employee regarding their job position. A person can have multiple employments at the same time. HR Core: Dienstverband | READ |
| Employment Timelines | The chronological sequence of events in the past pertaining to an individual’s employment within an organization, including start and end dates. It is based on the history table of HR Core. The endpoint contains the same fields as the endpoint employments. HR Core: Dienstverband Historie | READ |
| Employment Planned Changes | Changes in employment type, organization unit, job profile and amount of hours that will come in the future detailing the start and end dates of the change. HR Core: Indirecte Mutaties | READ |
| Employment Types | Show details of the employment types. HR Core: Soort Arbeidsrelatie | READ |
| Employment Work Schedules | The planned working hours and days for an employee within their employment. HR Core: Werkrooster | READ |
| Entitlements | Different users that have a certain entitlement. | READ |
| Job Profiles | Different profiles or functions existing for each role within the company. HR Core: Functie | READ |
| Job Families | Reference table that exposes the possible position groups or job families that can be logged. HR Core: Functiegroep | READ |
| File Upload | Ability of uploading files to a repository of an individual’s employment records, including certifications, diplomas, contracts and other personal documents. | WRITE |
| Leave Entitlements | Extra adjustments made to an employee’s leave entitlement due the decision of the employee to buy or sell a specific amount of leave hours. This endpoint will return only the information of the last 2 years. HR Core: Verlofrechten | READ |
| Leave Entitlements Changes | Extra adjustments made to an employee’s leave entitlement due to certain employment circumstances.This endpoint will return only the information of the last 2 years. HR Core: Verlofrecht Mutaties | READ |
| Leave Hours | Specific number of hours of leave taken or scheduled by an employee. This endpoint will return only the information of the last 2 years. HR Core: Verlof tijdvakken | READ |
| Leave Periods | Specific time frames during which an employee has some time off. This endpoint will return only the information of the last 2 years. HR Core: DV Verlof tijdvak | READ |
| Locations | Reference table that shows the possible locations. HR Core: | READ |
| Maternity Leave | Leave granted to an employee around the time of childbirth or adoption. HR Core: Ziekte zwangerschapverlof | READ |
| Name Assemble Order | Reference table that shows the possible ways to use the surname. HR Core: Gebruik achternaam | READ |
| Organization Units | Distinct business units, departments, divisions, etc within a larger organization that represent functional or geographical areas and how these are related to each other. HR Core: Organisatie eenheden | READ |
| Payroll Client | Potentially segments an organization into several sub-organizations or units, such as dividing a municipal partnership into individual municipalities, separating by companies, or by Collective Labor Agreement (CLA) criteria. HR Core: CEA-nummer | READ |
| Pay Components | The Enterprise system can share the number of hours of overtime, extra shifts etc. that are relevant for the payroll. | WRITE |
| Persons | An individual employee or worker within the organization, including some personal details. This could also contain people without (active) employment. Additionally, if the person has an employment which is out of the historicaldays, then the person won’t be retrieved neither. HR Core: Persoon | READ |
| Person Timelines | The chronological sequence of processed events in HR Core pertaining to a person within an organization. It is based on the history table of HR Core. The endpoint contains the same fields as the endpoint persons. HR Core: Persoon Historie | READ |
| Role Assignments | Allocation of specific roles or responsibilities to a person within the organization. The role assignment describes “who” is responsible for “what“ and “when“ within the organization unit. HR Core: Rol toewijzing | READ |
| Role Assignment Descriptions | Reference table that exposes the functions of roles that are identified within an organizational unit. HR Core: Rol Org. eenheid | READ |
| Role User Management | Reference table that exposes the functions of roles that are identified within an organizational unit. HR Core: Rol Org. eenheid | READ |
| Salary Details | Information regarding an employee’s salary, including base pay, payroll scale, seniority, … HR Core: Dienstverband | READ |
| Salary Details Planned Changes | Changes in Salary Details fields: guaranteedPayrollScale and guaranteedSeniority that will come in the future detailing the start and end dates of the change. HR Core: Indirecte Mutaties | READ |
| Salary Scales | Reference table that exposes the current set of payroll scales for a employment to determine the salary. HR Core: Salaris schaal | READ |
| Sick Leave | Leave granted to an employee due to illness, including the sickness periods, allowing them to recover without job or pay loss. HR Core: Ziekte algemeen | READ |
| Users | Individuals with unique identifiers who have access to an organization’s systems, resources or data and their entitlements. Youforce User account. | READ WRITE |
| Workflow | A defined series of tasks or steps to complete a business process, like setting up the study cost agreements. | WRITE |
| Work Patterns | The agreed schedule of working hours along the days and rest periods for an employee. This endpoint will return only the information of the last 12 months. HR Core: Werkpatroon | READ |
4. Security and Scopes
All available endpoints are secured using OAuth 2.0 and protected by scopes.
| Scope | Description | Affected endpoints |
|---|---|---|
| Youforce-Enterprise:GetPrivateContactDetails | Grants access to private contact details of the employees | GET /v1.0/persons GET /v1.0/persons/timelines Extra fields shown: social security number, addresses, e-mail addresses (business and private) and phone numbers (business and private) |
| Youforce-Enterprise:GetSocialSecurityNumber | Grants access to the Social Security Number (bsn) | GET /v1.0/persons Extra fields shown: socialSecurityNumber |
| Youforce-Enterprise:Get_Assignments | Grants access to Assignments data | GET /v1.0/assignments |
| Youforce-Enterprise:Get_CostAllocations | Grants access to Cost Allocations data | GET /v1.0/costAllocations |
| Youforce-Enterprise:Get_CostCenters | Grants access to Cost Centers data | GET /v1.0/costCenters |
| Youforce-Enterprise:Get_ContractTypes | Grants access to CostAllocations data | GET /v1.0/contractTypes |
| Youforce-Enterprise:Get_Country | Grants access to Country data | GET /v1.0/country |
| Youforce-Enterprise:Get_EmploymentExtensionPlannedChanges | Grants access to Employment Extension Planned Changes data | GET /extensions/v1.0/enterprise/employments/plannedChanges |
| Youforce-Enterprise:Get_EmploymentExtensions | Grants access to Employment Extensions data | GET /extensions/v1.0/enterprise/employments |
| Youforce-Enterprise:Get_EmploymentExtensionTimelines | Grants access to Employment Extension Timelines data | GET /extensions/v1.0/enterprise/employments/timelines |
| Youforce-Enterprise:Get_EmploymentPlannedChanges | Grants access to Employment Planned Changes data | GET /v1.0/employments/plannedChanges |
| Youforce-Enterprise:Get_Employments | Grants access to Employments data | GET /v1.0/employments |
| Youforce-Enterprise:Get_EmploymentTimeline | Grants access to Employment Timeline data | GET /v1.0/employments/timelines |
| Youforce-Enterprise:Get_EmploymentTypes | Grants access to Employment Types data | GET /v1.0/employmentTypes |
| Youforce-Enterprise:Get_EmploymentWorkSchedules | Grants access to Employment Work Schedules data | GET /v1.0/employmentWorkSchedules |
| Youforce-Enterprise:Get_Entitlements | Grants access to Entitlements data | GET /v1.0/entitlements |
| Youforce-Enterprise:Get_JobProfileExtensions | Grants access to Job Profile Extensions data | GET /extensions/v1.0/enterprise/jobprofiles |
| Youforce-Enterprise:Get_JobProfiles | Grants access to Job Profiles data | GET /v1.0/jobProfiles |
| Youforce-Enterprise:Get_JobFamilies | Grants access to Job Families data | GET /v1.0/jobFamilies |
| Youforce-Enterprise:Get_Locations | Grants access to Locations data | GET /v1.0/locations |
| Youforce-Enterprise:Get_LeaveEntitlementChanges | Grants access to Leave Entitlement Changes data | GET /v1.0/leaveEntitlementChanges |
| Youforce-Enterprise:Get_LeaveEntitlements | Grants access to Leave Entitlements data | GET /v1.0/leaveEntitlements |
| Youforce-Enterprise:Get_LeaveHours | Grants access to Leave Hours data | GET /v1.0/leaveHours |
| Youforce-Enterprise:Get_LeavePeriods | Grants access to Leave Periods data | GET /v1.0/leavePeriods |
| Youforce-Enterprise:Get_maternityLeave | Grants access to Maternity Leave data | GET /v1.0/maternityLeave |
| Youforce-Enterprise:Get_NameAssembleOrder | Grants access to Name Assemble Order data | GET /extensions/v1.0/enterprise/ nameAssembleOrder |
| Youforce-Enterprise:Get_OrganizationUnitExtensions | Grants access to Organization Unit Extensions data | GET /extensions/v1.0/enterprise/organizationunits |
| Youforce-Enterprise:Get_OrgUnit | Grants access to Organization Units data | GET /v1.0/OrganizationUnits |
| Youforce-Enterprise:Get_PayrollClients | Grants access to Payroll Clients data | GET /v1.0/payrollClients |
| Youforce-Enterprise:Get_PersonExtenionTimelines | Grants access to Person Extension Timelines data | GET /extensions/v1.0/enterprise/Persons/timelines |
| Youforce-Enterprise:Get_PersonExtensions | Grants access to Person Extensions data | GET /extensions/v1.0/enterprise/Persons |
| Youforce-Enterprise:Get_Persons | Grants access to Persons data | GET /v1.0/persons |
| Youforce-Enterprise:Get_PersonTimelines | Grants access to Person Timelines data | GET /v1.0/persons/Timelines |
| Youforce-Enterprise:Get_RoleAssignments | Grants access to Role Assignments data | GET /v1.0/roleAssignments |
| Youforce-Enterprise:Get_RoleAssignmentDescriptions | Grants access to Role Assignment Descriptions data | GET /v1.0/roleAssignmentDescriptions |
| Youforce-Enterprise:Get_RoleUserManagement | Grants access to Role User Management data | GET /v1.0/roleUserManagement |
| Youforce-Enterprise:Get_SalaryDetailPlannedChanges | Grants access to Salary Detail Planned Changes data | GET /v1.0/salaryDetails/plannedChanges |
| Youforce-Enterprise:Get_SalaryDetails | Grants access to Salary Details data | GET /v1.0/salaryDetails |
| Youforce-Enterprise:Get_SalaryDetailTimelines | Grants access to Salary Detail Timelines data | GET /v1.0/salaryDetails/timelines |
| Youforce-Enterprise:Get_SalaryScales | Grants access to Salary Scales data | GET /v1.0/salaryScales |
| Youforce-Enterprise:Get_SickLeaves | Grants access to Sick Leaves data | GET /v1.0/sickLeaves |
| Youforce-Enterprise:Get_Vacancy | Grants access to Vacancy data | GET /v1.0/vacancy |
| Youforce-Enterprise:Get_WorkPatterns | Grants access to Work Patterns data | GET /v1.0/workPatterns |
| Youforce-Enterprise:HSS_startWorkflow | Grants access to start workflows on Self Service | POST /v1.0/hires GET /v1.0/hires/{StatusId}/status POST /v1.0/persons/{PersonId}/contracts GET /v1.0/persons/{PersonId}/contracts/{StatusId}/status POST /v1.0/persons/{PersonId}/contracts/{ContractId}/adjustments GET /v1.0/persons/{PersonId}/contracts/{ContractId}/adjustments/{StatusId}/status |
| Youforce-Enterprise:Update_Identity | Enables to write back changes in the Identity of the Youforce User | PATCH /v1.0/users(employeeId={employeeId})/identity |
| Youforce-Enterprise:Upload_documents | Grants access to upload documents to the personal file system, like certificates, diplomas and other relevant documents | GET /v1.0/employees/documents/{TicketId}/status POST /v1.1/employees/{PersonId}/documents/{certificate, diploma, careerAgreement, careerMail, careerOther, performanceReview, appraisalReview} |
| Youforce-Enterprise:Write_ContactDetails | Enables to write back basic information like e-mail address and phone number to HR Core | POST /v1.0/contactDetails/{personCode} POST /v1.0/contactDetails/bulk |
| Youforce-Enterprise:Write_EmploymentExtensions | Grants access to write data back to the Core like Person extensions or Employment extensions | PATCH /extensions/v1.0/{domain}/persons/{id} PATCH /extensions/v1.0/{domain}/employments/{id} |
| Youforce-Enterprise:Write_PayComponents | Enables to write back changes for payroll calculation (hours & other paycomponents) | POST /v1.0/payComponents/{ComponentId} GET /v1.0/payComponents/{TicketId}/status |
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. - employmentType: Use this parameter to filter by the employment type code.
Available endpoints: Employment. - leaveEntitlementYear: Use this parameter to filter by the year of the leave entitlemente.
Available endpoints: LeaveEntitlements, leaveEntitlementChanges, leaveHours and leavePeriods.
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}