1. Overview

Domain Purpose:
The Learning domain enables integration capabilities like the exchange of relevant HR data needed for Learning Management System or Performance Management System who are responsible for the employee development process around personal and collective courses or appraisals.

Typical Use Cases:

  • Get all the relevant employee data for the learning systems
  • Get the organization structure for the approval of courses
  • Post a certificate or diploma to the personal file system after finishing a course

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


2. Domain model

Learning 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 BO4. 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
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
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 Beaufort. The endpoint contains the same fields as the endpoint employments. HR Core: Dienstverband Historie READ
Entitlements Different users that have a certain entitlement. 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
Job Profiles Different profiles or functions existing for each role within the company. HR Core: Functie 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
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
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
Users Individuals with unique identifiers who have access to an organization’s systems, resources or data and their entitlements. Youforce User account. READ
Workflow A defined series of tasks or steps to complete a business process, like setting up the study cost agreements. WRITE


4. Uploading Files

The possible file upload types are the following:

  • Appraisal review (beoordelingsgesprek)
  • Career agreement (loopbaanafspraak)
  • Career mail (correspondentie loopbaan)
  • Career other (overig loopbaan)
  • Certificate (certificaat)
  • Diploma (diploma)
  • Performance review (functioneringsgesprek)

The uploading of the files is asynchronous which allows the integrator to initiate a file upload and continue with other tasks without waiting for the upload to complete.
Our servers will process the file in the background, while the integrator can check the status of this process by making a query to the status endpoint (see below).


5. Security and Scopes

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

Scope Description Affected endpoints
Youforce-Learning:Get_Basic Grants access to basic employee & organisation data GET /v1.0/assignments
GET /v1.0/costAllocations
GET /v1.0/employments
GET /v1.0/employments/timelines
GET /v1.0/entitlements/{Entitlement}/users
GET /v1.0/jobProfiles
GET /v1.0/organizationUnits
GET /v1.0/persons
GET /v1.0/roleAssignments
GET /v1.0/users
Youforce-Learning:GetPrivateContactDetails Grants access to private contact details like address, phone number and email address of the employees GET /v1.0/persons
Extra fields shown: emailAddresses, phoneNumbers, addresses
Youforce-Learning:HSS_startWorkflow Grants access to start workflows on Self Service GET /v1.0/persons/{PersonId}/contracts/{ContractId}/trainingAgreements/{TicketId}/status
POST /v1.0/persons/{PersonId}/contracts/{ContractId}/trainingAgreements
Youforce-Learning: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}


6. 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:

These parameters filter records based on creation or modification dates:

  • 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.
  • 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

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. It doesn’t correspond to the block field in BO4.
    Available for all endpoints.
  • 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.


7. 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}


8. Swagger page

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