Knowledge base YouServe API's

  Q: How can I receive only changed records? A:  The From and To filter is available to receive changes in a given time range. The From and To filter option is available on most endpoints, except valueLists. Example employees: Returns (active) employee records that have changed within the provided date-time range.   https://api.youserve.nl/iam/v1.0/employees?from=2021-01-01T09:00:00.000Z &to=2022-01-10T14:00:00.000Z   Q: What does the 90 day retention policy signify? A:  At current, the retention policy on the data stored in for the IAM API is 90 days. Based on the following properties a record will be removed when the date defined for these properties is greater than 90 days in the past: validUntil  - all entities dischargeDate  - employments, employees endDate  - role assignments, assignments Q: Why do I see records with the with dischargeDates or endDates in the past? A: We support the notion of retroactive changes i.e. when a dischargeDate for an employment or endDate for an assignment is defined today for a date is set in the past. This can be the result of an administrative mistake. In this scenario, the record will remain available for 90 more days based on the mutation date (date when the change was made).   Q: Why do I not see all the properties mentioned in the data mapping document in my response? In the IAM API properties that do not have values defined in the core systems are hidden. For this reason there might be a different amount of properties available per record.   Q: What are extensions? A: Extensions are based on the customer-specific fields defined in the core application. These custom fields can be configured and returned as part of the API response body . As a customer I have a custom field named: “height“. As part of my integration it is important to know the height of my employees in order to validate their identity. With the extensions feature we are able to expose this field and value as part of the API response allowing the customer to validate the identity of employees with the help of their height. Extensions are only available for HR Core Business and for the Employees (employee entity) and Employments (contract entity) endpoint.   Q: Why do I have more than 1 record for my entities? A: As part of the IAM API we support support, historic, current and future changes. A change in the core is reflected by a new record in the IAM API, which can be referred to as “versions“. Each record has the following properties: validFrom - This reflects the date from which a record is considered valid, the “start date“ of the validity validUntil - This reflect the date from which a record is no longer valid, it’s “end date“ of the validity    

The File API allows you to download or upload files directly from YouServe, over HTTPS using the tool of your choice.

Publisher is a Client Application that can upload files of authorized business types and authorized tenants. The uploaded files can also be listed/downloaded.

Subscriber is a Client Application that can list/download/delete the files of authorized business types and authorized tenants.

The File API allows you to download or upload files directly from Youforce, over HTTPS using the tool of your choice.

Getting Started! Do you want to start using one of the Domain APIs? Please read more about how to, in this Article

Versions of the endpoint employees For the endpoint GET /employees there’ll be 2 versions available (status : sep ‘20). These versions are ‘header based’ available for API consumers.  The version is added to the header of the request: Example requesting v2.0 using postman   The functional difference between those versions is the following : V1 (DEPRECATED!) In this endpoint version we face a small issue that an employee in core system HRCB (r1) becomes a single employee in our MLM API output. As a result that a single person is returned multiple times in our API’s (see example below). Eventually this version will be phased out! Person: { personID : 123, name : Jan Jansen, address : ABC, contract : A1, validFrom : 01-02-2020, validUntil : 10-04-2020 } Person: { personID : 123, name : Jan Jansen, address : DEF, contract : B1, validFrom : 11-04-2020, validUntil : 10-06-2020 } Person: { personID : 123, name : Jan Jansen, address : DEF, contract : B2, validFrom : 11-06-2020, validUntil : 31-12-9999 }   V2 In this version V2 we’ve solved the above issue in V1, so we’ll return here in a correct way the current version of a unique person with the actual contract versions. We’ve included temporality on the ‘Person level' and also on the lower ‘Contracts level', so the API consumer is able to jump into conclusions very efficiently. Scenario : standard exposure / current person versions with current contract versions Person 1: { (current version) validFrom : 01-01-2020 validUntil : 31-12-9999 personID : 123, name : Jan Jansen, address : ABC, contract : A3, (current version) validFrom : 01-05-2020 validUntil : 31-12-9999 contract : B5 (current version) validFrom : 01-03-2020 validUntil : 31-12-9999 } Person 2: { (current version) personID : 345, name : Joke van der Laan, address : HJK, contract : A2, (current version) contract : B2 (current version) } …… Person 100 { (current version) personID : 964, name : Henk de Vries, address : VDW, contract : A1, (current version) contract : B4, (current version) contract : C1 (future version) contract C - version 1 validFrom 01-10-2020 --nextlink-- In the above V2 example we expose Person 1 with personId 123 who has two contracts (A, B). Each contract has its own versions. Contract A has two historical versions and one current version. Contract B has four historical versions and one current version. Scenario : active person has only one historical inactive contract The following scenario covers again Person 832 who’s having just one contract (A) which became historical (since yesterday). The endpoint will return his actual personal details with this (historical) contract data. So in case, there is no active contract, the response will show the last active contract version (latest historical). Person 72: { (current version) personID : 832, name : Piet van de Berg, address : DDS, contract : A3 (historical version) Scenario : active person is a ‘new hire’ with one future contract In the below scenario of Person 193, who’s having just one future contract (future hire). The /employee endpoint return actual person details with his contract details. Since there is no active contract, it will return the future contract version. Person 41: { (current version) personID : 193, name : John de Jong, address : HJA, contract : A1 (future version)

  Swagger documentation The following swagger page gives an overview of the endpoints: Payroll API   Endpoints Employees Full load or initial load To get the list of employee basic data of a tenant, the endpoint can be used without any additional parameters. GET https://api.youserve.nl/payroll/v1.0/employees   Incremental load To get the list of employee basic data of a tenant after a specific time, the changedAfter parameter should be included. Also it is possible to include the changedUntil parameter. GET https://api.youserve.nl/payroll/v1.0/employees?changedAfter=2020-05-19   Get employee by Id It is also possible to retrieve the data of a specific employee. GET https://api.youserve.nl/payroll/v1.0/employees/13161246   Employee benefits Full load or initial load To get the list of employee benefits of a tenant, the endpoint can be used without any additional parameters. GET https://api.youserve.nl/payroll/v1.0/employeeBenefits   Incremental load To get the list of employee benefits of a tenant after a specific time, the changedAfter parameter should be included. GET https://api.youserve.nl/payroll/v1.0/employeeBenefits?changedAfter=2020-05-19   Employee fixed payments Full load or initial load To get the list of employee fixed payments of a tenant, the endpoint can be used without any additional parameters. GET https://api.youserve.nl/payroll/v1.0/employeeFixedPayments   Incremental load To get the list of employee fixed payments of a tenant after a specific time, the changedAfter parameter should be included: GET https://api.youserve.nl/payroll/v1.0/employeeFixedPayments?changedAfter=2020-05-19   Employee one-off payments Full load or initial load To get the list of employee one off payments of a tenant, the endpoint can be used without any additional parameters. GET https://api.youserve.nl/payroll/v1.0/employeeOneOffPayments   Incremental load To get the list of employee one off payments of a tenant after a specific time, the changedAfter parameter should be included. GET https://api.youserve.nl/payroll/v1.0/employeeOneOffPayments?changedAfter=2020-05-19   File upload POST employees/{employeeId}/paylips Endpoint for uploading a payslip to the Personal File System of Visma Raet. The endpoint returns a  ticketId  . The document will be uploaded using the type of document provided in the request, or setting a type of document by default for that customer. If this document type is not provided, then the default ovSalaris is used. The API will automatically upload the file to the Personal File System. This is an asynchronized 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 payslips/{ticketId}/status Endpoint for getting the status of the uploaded file. The endpoint will return the status of the file. After the file is processed successfully the status Complete is returned.   Postman collection and environment As attachment you can find a zip file with the collection and the environment.  

What is the YouServe API? Through the YouServe API you can in integrate data and therefore giving your customers: an up-to-date list of the latest HR information in your application automatic on- and off-boarding of employees in your application HR Core system There is always an HR Core system in the centre of every customer implementation storing the employee data. With the API's we support  HR Core Business.   API library You can find the APIs at https://developers.youserve.nl/api-library   

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.  

The files which are related to the same “business” are functionally grouped in File types called “Business types”. File types are represented by an integer called “Business type id”.

  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.