Knowledge base YouServe API's

  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 establishmentUnit Establishment unit of the employee.   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 establishmentUnit establishmentUnit = 7449   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 managerPersonCode Person code of the manager backupManager Backup manager of the organization unit backupManagerPersonCode Person code of the backup 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.