The Learning API is intended for Learning Management systems and allows you to:
Read employees and organizational structures from Youforce to update the learning system
Upload certificates to the Youforce Personal File system of the customer
Domain model
Concepts
Employees
The object employee contains all personal and employment details of an employee.
Object attributes
An employee is a person with one or more employments.
Attributes person details
Attribute
Description
id
Unique id for the Person row within the tenant
personCode
The logical person code of the employee
Initials
The initials of the employee.
firstNames
The official given names of the employee as stored in the HR Core system
KnowAs
The name which is used by the employee as his first name
lastNameAtBirth
The last name at birth of the employee. Also known as the family name
lastNameAtBirthPrefix
The prefix of the last name at birth
lastName
The last which is currently used by the employee as his last name
lastNamePrefix
The prefix of the last name as used currently
nameAssembleOrder
Code of the assemble order that the core system uses for the last name. The assembly order is depending on the core system and the logic behind it.
partnerName
The partner last name
partnerNamePrefix
The prefix of the partner last name
titlePrefix
The formal title which will be used as a prefix before the name like Doctor, Professor, et cetera
titleSuffix
The formal title which will be used as postfix after the name like MSc or Master of Science
gender
Gender of the person. Supported values are Male / Female. Note: other type of genders will be shown as Not Known
birthDate
Date of birth
deceased
Indicated if the employee deceased
UserUID
Digital Identity of the user from the portal
emailAddresses
type
address
List of the addresses of the employee. The fields are:
type like Business, Private, et cetera
address
Addresses
type
street
houseNumber
houseNumberAdditional
locationDesignation
postalCode
city
region
country
List of the addresses of the employee. The fields are:
type like Home, Post, et cetera
street name
house number
house number additional
Location designation
Postal code
City
Region
Country code
phoneNumbers
type
number
list of phone numbers of the employee
type like Business, Home, Mobile, et cetera
number
communicationLanguage
Communication language
Attribute employment details
Attribute
Description
employeeID
Technical and unique id. the Id is unique within the entity and tenant.
employeeCode
Code of the employee
employmentCode
Logical code of the employment
company
Unique (alphanumeric) identifier of the company with which the contract is concluded
hireDate
The hire date of the employment
dischargeDate
The end date or discharge date of the employment.
originalHireDate
The first hire date or original hire date of an employee within the organization.
employmentType
Type of employment with a short name for type like Internal employee, contractor, "Wachtgelder"
jobProfile
job profile code of the employment The job profile is a code that refers to the entity job profile
organizationUnit
organization unit of employment. The organization unit is a code that refers to the entity organization units
workingAmount
amountOfWork
unitOfWork
periodOfWork
Work amount of employment.
The amount of work
Unit of work that specifies the amount of work like "hours", "days", et cetera
Period of work like "week" or "month"
contractType
Contract type of the employee. It is the code that refers to the entity contract type.
costCenter
Main cost center associated with the employee. It is the code that refers to the entity cost center.
classification
Classification of the employee. It is the code that refers to the entity Classification.
location
Location of the employee. It is the code that refers to the entity location.
salaryScale
Salary scale of the employee. It is the code that refers to the entity salary scale
Data mapping
Attributes person details
attribute
HR Core Business
personId
Technical id of the employee in HRCB
personCode
7014 - Uniek Persoonlijk ID (UPI) (If it is not filled in then the Medewerkercode - 22)
Initials
25 - Voorletters
firstNames
51 - Voornamen
KnowAs
165 - Roepnaam
lastNameAtBirth
24 - Achternaam
lastNameAtBirthPrefix
26 - Voorvoegsel
lastName
524 - Opgemaakte naam aanhef Note: In HRCB this field is combination of the last name and the last name prefix
lastNamePrefix
#NA
nameAssembleOrder
28 - Eigennaam code
partnerName
27 - Naam Partner
partnerNamePrefix
166 - Voorvoegsel Partner
titlePrefix
94 - Titel voor
titleSuffix
95 - Titel na
gender
36 - Geslacht
Mapping details: 1 or Man → Male 2, Vrouw, Woman → Female Other values will shown as Not Known
birthDate
35 - geboorte datum
deceased
Based on the date of deceased. If the employee is deceased the boolean is set to True 10302568 - Datum overlijden
UserUID
10523564 - PING ID
emailAddresses
type
address
Business : 7212 - E-mailadres Prive: 7213 - E-mailadres Prive
Addresses
type
street
houseNumber
houseNumberAdditional
locationDesignation
postalCode
city
region
country
Home:
391 - straat 392 - Huisnummer 393 - Huisnummer toevoeging
8099 - Locatie omschrijving
394 - Postcode 395 - Woonplaats 34 - Woonland
10205283 Regionaam Buitenland
Postal:
7572 - Straat Postadres 7573 - huisnummer Postadres 7574 - Huisnummer toev. adres
8100 Locatie omsch Postadres 7575 - Postcode Postadres 7576 - Plaats Postadres 7571 - Land
8101 Regionaam Buitenland
phoneNumbers
type
number
Home : 7376 - Telefoonnummer prive Mobile : 7377 - Telefoonnummer mobiel Business : 7374 - Telefoonnummer intern
addresses
communicationLanguage
10
Attribute employment details
Attribute
HR Core Business
employeeID
technical ID of the employee in HRCB
employeeCode
22 - Medewerkercode
employmentCode
#NA
company
18 - company code
hireDate
39 - Datum indienst
dischargeDate
10520479 - Geplande laatste datum indienst
originalHireDate
308 - Datum indienst organisatie
employmentType
7393 - Type Medewerker
jobProfile
97 - functie
organizationUnit
6000 - Organisatorische eenheid
workingAmount
amountOfWork
unitOfWork
periodOfWork
amount of work = 465 - Uren periode
perodOfWork = 463 - Dagen / uren per
*HRCB supports only amount of work in "hours" parttimePercentage is not available
contractType
contract type = 10204687
costCenter
cost center = 53
classification
classification = 474
location
location = 75
salaryScale
salaryScale = 10300574
Users
The object User contains the User Identity for Single Sign-On. The User Identity is stored in the User Management System of the Youforce portal and can be used to support Single Sign-On.
For HR Core Business the User Identity is already part of the employee endpoint.
Object attributes
attribute
example
description
id
c7e230db-2a7f-4ef0-ad1d-9d30e7d94a2f
User Identity of the employee for Single Sign On.
sourceId
XX123456
not relevant within the learning domain
identityId
null
not relevant within the learning domain
Organization units
The object Organization Units will provide all HR Data regarding the organization structure, like business Unit, department. Next to that, it describes in what way these are related to each other. Based on the organizational structure it’s clear ‘which' department is responsible for 'what’.
Object attributes
The organization unit and the role assignment how the organization is structured and who is responsible in which role.
Attributes Organization Unit
Attribute
Description
id
Unique Id of the organization Unit
shortName
Logical code of the organization Unit
fullName
Logical name of the organization Unit
parentOrgUnit
Id of the parent organization Unit In some core systems this relation can changed in during the timeline of an organization Unit.
organizationUnitType
Type of organization Unit
manager
Manager of the organization unit*
*Only for HR Core Business. For HR Core Beaufort the manager is part of the role assignment
managerPersonCode
Person code of the manager
Attributes Role Assignment
Attribute
Description
id
Unique Id of the record
OrganizationUnitId
Id of the organization unit the role assignment is effective for
roleCode
Code of the role. For instance the role manager is identified with the role code MGR.
personCode
Person who have this role for the specific organisation unit. The person code is a reference to the Person code in the employee
personId
Person who have this role for the specific organisation. The person id is a reference to the Person id in the employee table
startDate
Start date from which the role assignment is valid for that employee
endDate
End date from which the role assignment is valid for that employee
Data mapping
Attributes Organization Unit
Attribute
HR Core Business
id
Technical id from HRCB
shortName
548 - code OE
fullName
549 - Naam OE
parentOrgUnit
technical id of the parent Org unit
organizationUnitType
#N/A
managerId
7137 - manager
Attributes Role Assignment
Attribute
HR Core Business
id
Technical id from HRCB
OrganizationUnitId
548 - code OE
roleCode
549 - Naam OE
personCode
#N/A
personId
Reference to the Person Id
startDate
#N/A
endDate
#N/A
Job profiles
Object attributes
The object job profile contains the following attributes.
Attribute
Description
shortName
short name of the job profile
fullName
full name of the job profile
jobFamily
job family to which the job belongs.
Data mapping
Attribute
HR Core Business
shortName
Functie code
fullName
functie naam
jobFamily
Job family
Companies
Object attributes
The object company contains the following attributes.
Attribute
Description
id
identifier of the company
code
company code
fullName
full name of the company
ValidFrom
Start date of the version of the company
ValidUntil
End date of the version of the company
Data mapping
Attribute
HR Core Business (Supported level: Client)
id
mutkey
code
company code
fullName
company name
Contract types
Object attributes
The object contract type contains the following attributes.
Attribute
Description
code
contract type code
fullName
full name of the contract type
ValidFrom
Start date of the version
ValidUntil
End date of the version
Data mapping
Attribute
HR Core Business (Supported level: System)
code
contract type code
fullName
contract type name
Employment types
Object attributes
The object employment type contains the following attributes.
Attribute
Description
code
employment type code
fullName
full name of the employment type
ValidFrom
Start date of the version
ValidUntil
End date of the version
Data mapping
Attribute
HR Core Business (Supported level: Client)
code
employment type code
fullName
employment type name
Cost centers
Object attributes
The object cost center contains the following attributes.
Attribute
Description
code
cost center type code
fullName
full name of the cost center
ValidFrom
Start date of the version
ValidUntil
End date of the version
Data mapping
Attribute
HR Core Business (Supported level: Client)
code
cost center code
fullName
cost center name
Classifications
Object attributes
The object classification contains the following attributes.
Attribute
Description
code
classification code
fullName
full name of the classification
ValidFrom
Start date of the version
ValidUntil
End date of the version
Data mapping
Attribute
HR Core Business (Supported level: Client)
code
classification code
fullName
classification name
Locations
Object attributes
The object location contains the following attributes.
Attribute
Description
code
location code
fullName
full name of the location
ValidFrom
Start date of the version
ValidUntil
End date of the version
Data mapping
Attribute
HR Core Business (Supported level: Client)
code
location code
fullName
location name
Salary scales
Object attributes
The object salary scale contains the following attributes.
Attribute
Description
code
salary scale code
fullName
full name of the salary scale
ValidFrom
Start date of the version
ValidUntil
End date of the version
Data mapping
Attribute
HR Core Business (Supported level: Client)
code
salary scale code
fullName
salary scale name
Job families
Object attributes
The object job family contains the following attributes.
Attribute
Description
code
job family code
fullName
full name of the job family
ValidFrom
Start date of the version
ValidUntil
End date of the version
Data mapping
Attribute
HR Core Business (Supported level: System)
code
job family code
fullName
job family name
File upload
With the documents endpoint files, certificates and other documents can be uploaded for an employee to the Visma Personal File System (Personeelsdossier).
Asynchronous file upload
Learning systems can upload files, like certificates, diplomas for individual employees to the Personal File System of Visma Raet. The file upload is an a-synchronized process. After the file is uploaded the consumer will receive a ticket Id, which can be used to monitor the process of the file upload.
Swagger documentation
The following swagger page gives an overview of the endpoints:
Learning API
Endpoints
Employees
GET employees The endpoint GET employees gives a list of employees with the personal and employment details of an employee. GET https://api.youserve.nl/learning/v1.0/employees
GET employee by id The endpoint GET employee by id gives a list of the versions of the employee with the given id, including the personal and employment details of the employee. GET https://api.youserve.nl/learning/v1.0/employees/1
GET employee by person code The endpoint GET employee by person code gives a list of the versions of the employee with the given person code, including the personal and employment details of the employee. GET https://api.youserve.nl/learning/v1.0/employees?personcode=1001
Users
GET users The endpoint GET users return user information for a single employee. For the User Identity is relevant for consumers who want to implement the Single Sign-On solution of Visma Raet. GET https://http://api.youserve.nl/learning/v0.1/users(employeeId=1005)
Organization units
GET organizationUnits The endpoint GET organizationUnits gives the organization structure of the tenant. It is possible to include filters by changedAfter and changeUntil parameters. GET https://api.youserve.nl/learning/v1.0/organizationUnits GET https://api.youserve.nl/learning/v1.0/organizationUnits??changedAfter=2020-10-08&changedUntil=2020-11-17
GET organizationUnit by id The endpoint GET organizationUnits by id gives the versions of the organizational unit with the given id. GET https://api.youserve.nl/learning/v1.0/organizationUnits/1
GET organizationUnit by short name The endpoint GET organizationUnit by short name gives the versions of the organizational unit with the given short name. GET https://api.youserve.nl/learning/v1.0/organizationUnits?shortName=OrgUnit1
GET roleAssignments The endpoint GET roleAssignments gives a list persons “who” are responsible in “which” Role for a specific part of the organization. It is possible to include filters by changedAfter and changeUntil parameters. GET https://api.youserve.nl/learning/v1.0/roleassignments GET https://api.youserve.nl/learning/v1.0/roleassignments?changedAfter=2020-10-08&changedUntil=2020-11-17
Job profiles
GET jobProfiles The endpoint GET jobProfiles gives a list of job profiles of the tenant details of an employee. GET https://api.youserve.nl/learning/v1.0/jobProfiles
Companies
GET companies The endpoint GET companies gives a list of company versions of the tenant. GET https://api.youserve.nl/learning/v1.0/companies GET https://api.youserve.nl/learning/v1.0/companies?changedAfter=2020-10-08&changedUntil=2020-11-17
GET company by code and validAt The endpoint GET company by code and valid at gives the version of the company with the given code and valid at the given date. If the validAt parameter is not set, then the current date is taken. GET https://api.youserve.nl/learning/v1.0/companies/1000?validat=2020-10-01
Contract types
GET contractTypes The endpoint GET contractTypes gives a list of contract type versions of the tenant. GET https://api.youserve.nl/learning/v1.0/contractTypes GET https://api.youserve.nl/learning/v1.0/contractTypes?changedAfter=2020-10-08&changedUntil=2020-11-17
GET contractType by code and validAt The endpoint GET contractType by code and valid at gives the version of the contract type with the given code and valid at the given date. If the validAt parameter is not set, then the current date is taken. GET https://api.youserve.nl/learning/v1.0/contractTypes/1000?validat=2020-10-01
Employment types
GET employmentTypes The endpoint GET employmentTypes gives a list of employment type versions of the tenant. GET https://api.youserve.nl/learning/v1.0/employmentTypes GET https://api.youserve.nl/learning/v1.0/employmentTypes?changedAfter=2020-10-08&changedUntil=2020-11-17
GET employmentType by code and validAt The endpoint GET employmentType by code and valid at gives the version of the employment type with the given code and valid at the given date. If the validAt parameter is not set, then the current date is taken. GET https://api.youserve.nl/learning/v1.0/employmentTypes/0001?validat=2020-10-01
Cost centers
GET costCenters The endpoint GET costCenters gives a list of cost centers versions of the tenant. GET https://api.youserve.nl/learning/v1.0/costCenters GET https://api.youserve.nl/learning/v1.0/costCenters?changedAfter=2020-10-08&changedUntil=2020-11-17
GET costCenter by code and validAt The endpoint GET costCenter by code and valid at gives the version of the cost center with the given code and valid at the given date. If the validAt parameter is not set, then the current date is taken. GET https://api.youserve.nl/learning/v1.0/costCenters/03?validat=2020-10-01
Classifications
GET classifications The endpoint GET classifications gives a list of classifications versions of the tenant. GET https://api.youserve.nl/learning/v1.0/classifications GET https://api.youserve.nl/learning/v1.0/classifications?changedAfter=2020-10-08&changedUntil=2020-11-17
GET classification by code and validAt The endpoint GET classification by code and valid at gives the version of the classification with the given code and valid at the given date. If the validAt parameter is not set, then the current date is taken. GET https://api.youserve.nl/learning/v1.0/classifications/0001?validat=2020-10-01
Locations
GET locations The endpoint GET locations gives a list of locations versions of the tenant. GET https://api.youserve.nl/learning/v1.0/locations GET https://api.youserve.nl/learning/v1.0/locations?changedAfter=2020-10-08&changedUntil=2020-11-17
GET location by code and validAt The endpoint GET location by code and valid at gives the version of the location with the given code and valid at the given date. If the validAt parameter is not set, then the current date is taken. GET https://api.youserve.nl/learning/v1.0/locations/1001?validat=2020-10-01
Salary scales
GET salaryscales The endpoint GET salaryscales gives a list of salaryscales versions of the tenant. GET https://api.youserve.nl/learning/v1.0/salaryScales GET https://api.youserve.nl/learning/v1.0/salaryScales?changedAfter=2020-10-08&changedUntil=2020-11-17
GET salaryscale by code and validAt The endpoint GET salaryscale by code and valid at gives the version of the salary scale with the given code and valid at the given date. If the validAt parameter is not set, then the current date is taken. GET https://api.youserve.nl/learning/v1.0/salaryScales/1001?validat=2020-10-01
Job families
GET jobFamilies The endpoint GET jobFamilies gives a list of job family versions of the tenant. GET https://api.youserve.nl/learning/v1.0/jobFamilies GET https://api.youserve.nl/learning/v1.0/jobFamilies?changedAfter=2020-10-08&changedUntil=2020-11-17
GET jobFamily by code and validAt The endpoint GET jobFamily by code and valid at gives the version of the job family with the given code and valid at the given date. If the validAt parameter is not set, then the current date is taken. GET https://api.youserve.nl/learning/v1.0/jobFamilies/DEV?validat=2020-10-01
File upload
POST employees/{personId}/documents/certificate Endpoint for uploading a certificate to the Personal File System of Visma Raet. The endpoint returns a ticketId . The file will be stored in a standard folder for certificates. The name of the folder is “certificaat”. This name cannot be changed by the end-user or the API. POST https://api.youserve.nl/learning/V1.0/api/employees/1/documents/certificate
The API will automatically upload the file to the Personal File System. This is an a-synchronized process with an automatic retry mechanism in case the file systems is not available. The retry mechanism will try to upload the file in a maximum of 6 hours. After this period the file will be rejected with a message. Also if the file is too big (maximum 4 Mb) or isn’t a PDF file, the upload will be rejected.
GET documents/{TicketId}/status Endpoint for getting the status of the file upload. The endpoint will return the status of the file. After the file is processed successfully the status Complete is returned. GET https://api.youserve.nl/learning/v1.0/employees/documents/{{TicketId}}/status
Postman collection and environment
As attachment you can find a zip file with the collection and the environment.
Sandbox environment
Single Sign-On
Sandbox environment
Q: Is there a test or sandbox environment available for developers?
A: Yes, we have different a sandbox environment available. Please contact us if you want to access the environment.
Single Sign-On
Q: I want to use the API together with the Single Sign-On solution of Visma Raet. What should I know about that?
A: For Single Sign-On you need to keep the User Identify of the employee in your system. This User Identity will be used to switch between the Youforce module and your application for a single employee.