Integration API for Enterprise Domain GENERAL AVAILABLE

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.

3.1 Training Agreements

Start a Training Agreement workflow for a person’s contract, and check on its progress. This triggers a workflow in the HR Self Service system — the request is accepted immediately, but processing happens asynchronously, so you’ll need to poll the status endpoint to find out what actually happened.

Start a Training Agreement

Path parameters

Request body

Example request

{
  "trainingName": "Project Management Fundamentals",
  "trainerName": "Jane Smith",
  "price": 450.00,
  "startDate": "2026-03-01",
  "endDate": "2026-03-15",
  "additionalExplanation": "Required for upcoming role change"
}

Example response — 202 Accepted

{
  "id": "fede49ce-7043-482d-aba8-152478712c4b"
}

Keep this id — you’ll need it to check the outcome.

Possible responses

Check the status

Example response — 200 OK

{
  "id": "fede49ce-7043-482d-aba8-152478712c4b",
  "status": "Completed",
  "workflowName": "Studieovereenkomst",
  "startActivity": "Behandelen PA",
  "startButton": "verzenden",
  "hrssWorkflowStatus": {
    "data": {
      "companyId": "4028868",
      "isActive": true,
      "currentActivity": "Tekenen",
      "endStatus": "InProgress",
      "endStatusName": "",
      "workflowInstanceId": 233900
    },
    "workflowInstanceId": 233900
  },
  "errorDetails": null
}

Recommended check for “is this actually done”: don’t stop at status: "Completed" alone — that only confirms your submission succeeded. Poll until hrssWorkflowStatus.data.isActive is false, then read endStatus (OK/NOK) for the outcome. If status comes back as Error or InternalError, the submission itself failed and no workflow was started — see errorDetails (when present) for more information, or contact support.

Possible responses

Typical flow

1. POST the Training Agreement → receive 202 Accepted with an id.
2. GET the status using that id.
3. If status is InProgress, wait and try again.
4. Once status is Completed, look at hrssWorkflowStatus.data.isActive:
   • If true, the workflow is still being processed internally by your organization (e.g. pending signatures/approvals) — keep polling.
   • If false, check hrssWorkflowStatus.data.endStatus for the final outcome (OK or NOK).
5. If status is Error or InternalError, the request could not be submitted — check errorDetails if present, or contact support.

3.2 Vacancy endpoint

The Vacancy entity is the trigger of the recruitment process. Within the HR Core module, HR Self Service (HSS) managers start a vacancy based on an open position or an additional staffing need. Once a vacancy is approved by the company in HSS, it becomes the starting point for one or multiple recruitment cases (single or multiple employees).

The Recruitment API vacancy endpoint exposes this vacancy data to external recruitment systems so that:

• new vacancies can be published for recruitment, and
• existing vacancies can be kept in sync when they are updated in HR Core Self Service.

Note on updates: the vacancy can be edited after initial publication (HSS provides a vacancy overview with edit capability). Integrators should treat repeated GET calls with the same VacancyCode as an upsert: if the code is unknown, create the vacancy; if it already exists, apply the payload as an update.

Vacancy fields

The vacancy entity contains general information (code, title, etc.), job-related information (job profile, job level, organizational unit, etc.), and process information (start/end date, number of positions required).

PII note: owner and ownerEmailAddress are personal data under GDPR/AVG. Consumers must transmit and store this data encrypted (TLS in transit, encryption at rest) and must not log or persist it in plain text.

3.3 Hiring / Rehiring process

This endpoints help to onboard a new employee, or create a new contract for someone who has worked for the organization before. All actions are asynchronous: your request is accepted immediately, and you then poll a status endpoint to find out what actually happened.

The process

1. New hire — if this is a brand-new person, submit a hire directly.
2. In case of a rehire — if the candidate have worked here before, search for them first using a small set of identifying fields.
3. Rehire — if found, create a new contract for that existing person instead of creating a duplicate.
4. Later changes — once someone is hired, changes to their contract (job, hours, salary, etc.) go through a separate contract-adjustment call, not through the hire endpoint again.

Targeting a specific workflow: X-Raet-Workflow

Every POST action below supports an optional X-Raet-Workflow header, letting you target a specific workflow configured for your tenant for that one call, instead of using the default. Some actions may support their own specific set of workflow names — check with your implementation contact for the values available to you.

Attachment rules

Apply to the files array on every endpoint below that accepts it:

• The combined size of all attachments in a single request must not exceed 23 MB.
• File names may only contain: uppercase letters (A–Z), lowercase letters (a–z), numbers (0–9), and the symbols space, +, -, _, (, ), [, ], {, }, ., :, ;.

1. Hire a new employee

POST /{domain}/v1.0/hires

Request body — key fields

Example — minimal hire

POST /{domain}/v1.0/hires

{
  "lastNameAtBirth": "Smit",
  "lastNameAtPrefix": "van de",
  "knownAs": "Alex",
  "initials": "AS",
  "firstNames": "Alexander Simon",
  "gender": 1,
  "birthDate": "1985-06-15",
  "emailAddress": "alex.smith@example.com",
  "employmentDetails": {
    "payrollClientCode": "23625",
    "payrollInstitutionCode": "1",
    "hireDate": "2023-10-01",
    "employeeType": "V",
    "organizationUnit": 914,
    "jobProfile": "17",
    "amountOfHours": 20
  }
}

Response — 202 Accepted

{ "id": "fede49ce-7043-482d-aba8-152478712c4b" }

Keep this id to check the outcome (see below).

2. Check if the candidate already exists (before a rehire)

GET /{domain}/v1.0/persons/search

Only use a small, necessary set of search fields — this endpoint is deliberately limited for privacy reasons. Available fields: lastNameAtBirth, lastNameAtBirthPrefix, birthDate, birthPlace, knownAs.

GET /{domain}/v1.0/persons/search?lastNameAtBirth=VERWAAL&birthDate=1980-03-19

If a match is found, use that person’s id for the rehire call below instead of creating a new hire.

3. Rehire — new contract for an existing person

POST /{domain}/v1.0/persons/{personId}/contracts

Same request body fields as a new hire (§1). {personId} comes from the search above.

If the person has an active contract this rehire relates to, you can additionally identify it via:

Response: 202 Accepted with { "id": "..." }, same as a new hire.

4. Change an existing contract

POST /{domain}/v1.0/persons/{personId}/contracts/{contractId}/Adjustments

For changes to a contract that’s already active — job profile, hours, salary, or ending it.

POST /{domain}/v1.0/persons/35002/contracts/1/Adjustments

{
  "effectiveDate": "2024-01-01",
  "employeeType": "V",
  "contractType": "01",
  "organizationUnit": 914,
  "jobProfile": "4000",
  "amountOfHours": 20,
  "salaryDetails": {
    "payScale": "10",
    "payScaleStep": "4"
  }
}

Response: 202 Accepted with { "id": "..." }.

5. Checking the outcome

Every POST above is asynchronous. Poll the matching status endpoint using the id you got back:

Example response

{
    "id": "f42a3ec1-96cf-4ae1-94fa-ba68a6e0e57a",
    "status": "Completed",
    "workflowName": "YF API - Nieuwe Medewerker",
    "startActivity": "Youforce API",
    "startButton": "verzenden",
    "hrssWorkflowStatus": {
        "data": {
            "companyId": "4028868",
            "isActive": true,
            "currentActivity": "Aanvullen LG",
            "endStatus": "InProgress",
            "endStatusName": "",
            "workflowInstanceId": 1063367
        },
        "workflowInstanceId": 1063367
    }
}

Recommended check for “is this actually done”: poll until hrssWorkflowStatus.data.isActive is false, then read endStatus for the result.

Notes

• customFields lets you pass additional values not covered by the named fields above, if agreed with your implementation contact.

3.4 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

3.5 Write-Back Pay Components

A pay component is an individual building block used to describe or calculate an employee’s pay (in Dutch: looncomponent/salariscomponent) — think “a defined type of pay-related item,” not the employee’s total salary.

Finding valid element codes

Not every field can be written through this endpoint — only elements enabled for this purpose for your organization. Check the Employment Extensions entity for the employment you’re updating: each entry there includes a bo4FieldCode value, and that’s exactly what you pass as elementCode here. If a code isn’t listed there, it isn’t usable through Pay Components.

Writing pay components

POST /{domain}/v1.0/PayComponents/{employment}

Body: an array of:

Maximum 100 elements per request, and no two entries can share the same elementCode.

Example

POST /wfm/v1.0/PayComponents/55555-1

[
  { "elementCode": "pcf21", "value": "125.50", "effectiveDate": "2026-01-01" }
]

Response — 200 OK

{
  "ticketId": "fede49ce-7043-482d-aba8-152478712c4b",
  "status": "None",
  "errorMessage": null,
  "employmentCode": "55555-1",
  "payComponents": [
    { "elementCode": "pcf21", "value": "125.50", "effectiveDate": "2026-01-01" }
  ]
}

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

Checking the outcome

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

GET /wfm/v1.0/PayComponents/fede49ce-7043-482d-aba8-152478712c4b/status

{
  "ticketId": "fede49ce-7043-482d-aba8-152478712c4b",
  "status": "Complete",
  "errorMessage": null,
  "employmentCode": "55555-1",
  "payComponents": [
    { "elementCode": "pcf21", "value": "125.50", "effectiveDate": "2026-01-01" }
  ]
}

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.
• 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}
  
• GET /v1.0/salaryDetailtimelines:
  This behavior has been incorporated as part of the salaryDetails endpoint –> GET /v1.0/salaryDetails/Timelines
  
• GET /v1.0/salaryDetailtimelines/{id}:
  This behavior has been incorporated as part of the salaryDetails endpoint –> GET /v1.0/salaryDetails/Timelines/{id}